Skip to content

Latest commit

 

History

History
74 lines (61 loc) · 4.71 KB

CONTRIBUTING.md

File metadata and controls

74 lines (61 loc) · 4.71 KB

Contributing

Please do contribute! Issues and pull requests are welcome. When contributing to this repository, please first discuss the change you wish to make via issue or pull request.

Thank you for your help improving software!

All contributions to the source code must be cryptographically signed by the author’s PGP key or Github's key. Code signing guide.

Pull Request Process

Making your changes

  • Fork the repository on GitHub.
  • Create a new branch for your changes.
  • Make your changes.
  • Make sure you include tests (if applicable).
  • Make sure the test suite passes after your changes.
  • Commit your changes into that branch.
  • Use descriptive and meaningful commit messages.
  • If you have a lot of commits, squash them into a single commit.
  • Make sure you use the -S flag when committing as explained above.
  • Push your changes to your branch in your forked repository.

Submitting the changes

Submit a pull request via the normal GitHub UI.

  • Describe the pull request's impact on the project in the title, as follows:
    • Added - for new features.
    • Changed - for changes in existing functionality.
    • Deprecated - for once-stable features removed in upcoming releases.
    • Removed - for deprecated features removed in this release.
    • Fixed - for any bug fixes.
    • Security - to invite users to upgrade in case of vulnerabilities.
    • [WIP] - DO NOT USE in master branch
  • Include the purpose of this Pull Request in the description. For example: This is a spike to explore…, This simplifies the display of…, This fixes handling of…
  • Consider providing an overview of why the work is taking place (with any relevant links); don’t assume familiarity with the history.
  • Remember that anyone could be reading this Pull Request, so the content and tone may inform people other than those taking part, now or later.
  • Be explicit about what feedback you want, if any: a quick pair of 👀 on the code, discussion on the technical approach, critique on design, a review of copy.
  • Be explicit about when you want feedback, if the Pull Request is work in progress, say so. A prefix of “[WIP]” in the title is a simple, common pattern to indicate that state.
  • @mention individuals that you specifically want to involve in the discussion, and mention why. (“/cc @rowland007 for clarification on this logic”)
  • @mention teams that you want to involve in the discussion, and mention why. (“/cc @github/security, any concerns with this approach?”)

After submitting

  • Do not use your branch for any other development, otherwise further changes that you make will be visible in the PR.

Feeback

Offering feedback

  • Familiarize yourself with the context of the issue, and reasons why this Pull Request exists.
  • If you disagree strongly, consider giving it a few minutes before responding; think before you react.
  • Ask, don’t tell. (“What do you think about trying…?” rather than “Don’t do…”)
  • Explain your reasons why code should be changed. (Not in line with the style guide? A personal preference?)
  • Offer ways to simplify or improve code.
  • Avoid using derogatory terms, like “stupid”, when referring to the work someone has produced.
  • Be humble. (“I’m not sure, let’s try…”)
  • Avoid hyperbole. (“NEVER do…”)
  • Aim to develop professional skills, group knowledge and product quality, through group critique.
  • Be aware of negative bias with online communication. (If content is neutral, we assume the tone is negative.) Can you use positive language as opposed to neutral?
  • You may use emoji to clarify tone. Compare “:sparkles: :sparkles: Looks good :+1: :sparkles: :sparkles:” to “Looks good.”

Responding to feedback

  • Consider leading with an expression of appreciation, especially when feedback has been mixed.
  • Ask for clarification. (“I don’t understand, can you clarify?”)
  • Offer clarification, explain the decisions you made to reach a solution in question.
  • Try to respond to every comment.
  • Link to any follow up commits or Pull Requests. (“Good call! Done in 1682851”)
  • As a last resort, if there is growing confusion or debate, ask yourself if the written word is still the best form of communication. Talk (virtually) face-to-face, then mutually consider posting a follow-up to summarize any offline discussion (useful for others who be following along, now or later).

Contributors