Answer Submission Process

Writing a new answer

1. Choose a question to answer

• Each of the questions we would like to answer is a Github Issue in the kite-answers/answers repository.
• Choose any open unassigned github issue.
• Assign the issue to yourself within Github.
• If the issue has a cluster assigned, then it is part of a group of related questions. The cluster is visible as a link under the milestones github tab. If you answer one question in a cluster, assign yourself to each of the answers in the cluster. Since the answers are related, there will be shared context between them and it is more efficient to have one author learn the relevant material and write all of the corresponding solutions.

2. Before starting on an issue, please follow this question and answer checklist:

Since our issues are auto-generated, some of the questions are not part of the scope of Kite Answers. Before starting on any answer, please check the following:

Is the issue in the style of Kite Answers

As described in the "Governing Philosophy" section of the High-Level Guidelines, Kite Answers doesn't provide tutorial or blog-length answers. We provide targeted solutions to questions that arise in the midst of programming.

For example, a question asking "How to implement mergesort" is not appropriate for our format. This question merits a full tutorial and isn't likely to occur during standard programming tasks. On the other hand "How to sort a list" is a commonly occurring problem that can be simply addressed.

If an issue is not easily addressed in our format, and might be better served by another resource, use the close-tutorial label and close the issue.

Is the issue about a Python 2 question?

If the anwer is yes, then label the issue close-python-2 and close it.

Is the issue a "how to" question?

If no, then label the issue close-not-how-to and close it.

Examples of “how to” questions:

• "Python: multiple prints on the same line"
• "How can I read inputs as numbers?"

Examples of not-"how to" questions:

• user wants help with an error: "ValueError: could not convert string to float: id"
• user wants help with an error: "IndexError: list index out of range and python"
• conceptual question with no clear answer: "How do I protect Python code?"
• Question about general Python syntax, a running code snippet isn't required to answer it: "What exactly does += do in python?"

Does the how-to question require sandbox features we don't provide?

If the questions requires code samples that render images, make HTTP requests, serve HTTP requests, etc., add the label sandbox-incapable and move on.

The sandbox currently has some advanced functionality that we need to document in the style guide. Until that's there we should hold off on writing answers that require it. We don't want to close these because we will be able to get to them down the road.

In the meantime, adding the sandbox-incapable label will exclude them from your and others' searches for answers to write.

Examples:

• The answer would need code blocks that aren’t executable by our Python sandbox
• Contains another programming language: "How to call a Python function from Node.js"
• Requires use of an AWS server: "Unable to install boto3" or "How do I use boto3"
• Relates to setting up a Python environment: "How do I install Tensorflow on Windows?"

Is the question in the top 5-10% in terms of difficulty or length?

If the anwer is yes, then label the issue close-high-difficulty and close it.

These answers will be low on the traffic we get per writing calorie, so we shouldn't write them.

Example * How does numpy.newaxis work and when to use it?

If all is well, assign yourself to the Issue

If everything looks good and you're starting work, assign yourself to the Github Issue so others don't start working on it at the same time.

3. Answer the question

• Refer to the keywords: the question being searched may be broader than the specific StackOverflow question being asked, and may require multiple Answers (separate .md files) or multiple Solutions (separate headings in one Answer file)
• Read the entire StackOverflow page for the question, including the question, all answers, and all comments
• Build an outline of your answer, including a list of all reasonable solutions, and any information that will be useful when writing your answer
• Using the style guide and code examples, craft an answer to the question in your issue using the style guide. You should create a new file for each answer and use markdown formatting

4. Review your Answer

• Check your answer in the live editing environment.
• Each code block should be runnable.
• Make sure you added short headings to your solutions.
• Make sure you linked all identifiers to their documentation using kite-sym links.

5. Submit your Answer for review

• Create a pull request for your answer in the “kite-answers/answers” repository
• Information to include in the pull request
  • Title: same title as used in your Answer
  • Body line 1: "Closes [issue number]"
    • e.g. "Closes #1967"
  • Body line 2: [url of stack overflow article from the github issue]
  • Feel free to include any other information you would like the reviewer to know or keep in mind, or any questions you'd like feedback on.
• Submit each answer as one .md file
  • The file should be in the /answers/posts/ subdirectory
• Add a ready-for-review label.

Revising an Answer

To improve the quality of answers, we incorporate rounds of feedback from reviewers before final publication. The process is summarized in the process diagram below.

During the review process, an answer is in one of several stages indicated by the Pull Request label. To advance a solution to the next stage, change the label. This is usually accompanied by an additional commit including revisions, or a comment for discussion.

In each of the stages there is a queue of answers. These will be emptied daily by the relevant parties: author (grey), reviewer (blue), and manager (orange).

Priority

For timely feedback, queues should be emptied in the following order:

• Author
  1. feedback-requested
  2. Create new PR

By incorporating previous feedback first, you can improve before starting to work on something new.

• Reviewer

  1. reviewer-discussion
  2. ready-for-review

• Manager

  1. final-discussion
  2. final-review

Viewing Queues

Queues are viewable by search terms in the GitHub Pull Request Page:

https://github.com/kite-answers/answers/pulls

By bookmarking the result of a specific query, you can quickly view the contents of various queues. Search terms for the queues are:

feedback-requested : is:open is:pr author:[github username] label:feedback-requested

Others : is:open is:pr label:[queue name]

ready-for-review

In this phase, a Reviewer fully reads the answer and its corresponding keywords and StackOverflow post. They ensure that the answer fully addresses the question or questions being asked and follows the Kite Answers Style.

Feedback can be given via direct edits in the code, or a comment on the PR, as the Reviewer prefers.

If changes need to be made, they assign the answer to feedback-requested for the original Author to implement changes.

If the solution is of publishable quality, the Reviewer assigns the answer to final-review.

A single reviewer should provide feedback to a question for clarity and consistency. To do this, the reviewer should assign themselves as a reviewer to the question. To filter PRs that are assigned to you, use the search filter reviewed-by:[Name].

feedback-requested

This is the Author queue for implementing improvements to an answer.

The author is responsible for implementing all changes to their answer in order make it publishable quality.

This state can be reached from several starting points:

• After ready-for-review: A Reviewer has provided feedback.

  • Author can implement changes and return to ready-to-review
  • Author can discuss the feedback and label as reviewer-discussion

• After reviewer-discussion: A Reviewer has added a new comment to an ongoing discussion.

  • Author can implement changes and label as ready-to-review if they are satisfied with the discussion.
  • Author can continue the add a new comment to an ongoing discussion and label as reviewer-discussion

• After final-review: A Manager has provided feedback.

  • for minor changes Author can implement changes and label as final-review
  • for large changes Author can implement changes and label as review-requested. Sending the answer back to a Reviewer allows them to learn from the Manager feedback, streamlining the process in the future.
  • Author can discuss feedback and label as final-discussion

• After final-discussion: A Manager has added a new comment to an ongoing discussion.

  • Author can implement changes and label as either review-requested or final-review depending on the size of the change. (See previous)
  • Author can discuss feedback and label as final-discussion

reviewer-discussion (Optional)

This is the Reviewer queue for interactive discussion.

After providing comments on the discussion, the Reviewer should label as feedback-requested

final-review

This is the Manager queue for providing detailed review of solutions.

After reviewing the solution, the Manager will either comment or promote to publication-ready.

final-discussion (Optional)

This is the high-priority Manager queue for ongoing discussions.

After replying to a comment, the Manager with label as feedback-requested.

Git Command Reference

I use a lot of git cli commands when working on my answer, I'll share them below!

Creating a branch

Before creating a branch, ensure you're using the latest version of master. Then create your branch.

git checkout master; git pull
git checkout -b <git username>-<issue details>

Pushing your markdown file

After you've created and written your markdown file, you're ready to push it!

The following command will display any files you changed on your branch after you checked it out. Copy and paste the name of your markdown file in the "Changes not staged for commit" or "Changes to be committed" section.

git status

Paste your file name into the following command to add it to staging. Then run the next command to commit it. Example: git add example.md git commit -m "Create example.md"

git add <file name>
git commit -m <Write a commit message in double quotations>

After you've committed your message, call push. Pushing on a branch whose upstream isn't set will paste the command you should run in chat.

git push

Copy the output of the command above and paste it directly into the terminal. After you've pasted it, you will see a link to automatically open your pull request!

Deleting extra files

To see the files you've edited on your branch, run the following command

git status

If there's a file you don't want to have committed to staging or pushed, run the following to remove it.

rm posts/<file_name>
# you add files you want to remove in git
git add posts/<file_name>

How to reset a branch

Sometimes we mess up and want to reset our branch back a commit or two. Run the following command to reset back n commits. Please note that this is nearly permanent!

git reset --hard HEAD~<n>

Further Reading Resetting branches is dangerous, read more here before you do anything that could do wrong!