Skip to content

Latest commit

 

History

History
121 lines (95 loc) · 5.48 KB

CONTRIBUTING.md

File metadata and controls

121 lines (95 loc) · 5.48 KB
Raw

We welcome contributions from the community. Please read the following guidelines carefully to maximize the chances of your PR being merged.

Communication

  • Before starting work on a major feature, please reach out to us via GitHub, Slack, email, etc. We will make sure no one else is already working on it and ask you to open a GitHub issue.
  • A "major feature" is defined as any change that is > 100 lines of code altered (not including tests), or changes any user-facing behavior. We will use the GitHub issue to discuss the feature and come to agreement. This is to prevent your time being wasted, as well as ours. The GitHub review process for major features is also important so that organizations with commit access can come to agreement on design. If it is appropriate to write a design document, the document must be hosted either in the GitHub tracking issue, or linked to from the issue and hosted in a world-readable location.
  • Small patches and bug fixes don't need prior communication.

Coding style

Submitting a PR

  • Fork the repo.
  • Create your PR.
  • Tests will automatically run for you.
  • We will not merge any PR that is not passing tests.
  • PRs are expected to have 100% test coverage for added code. This can be verified with a coverage build. If your PR cannot have 100% coverage for some reason please clearly explain why when you open it.
  • All code comments and documentation are expected to have proper English grammar and punctuation. If you are not a fluent English speaker (or a bad writer ;-)) please let us know and we will try to find some help but there are no guarantees.
  • Your PR title should be descriptive, and generally start with a subsystem name followed by a colon. Examples:
    • "docs: fix grammar error"
    • "http conn man: add new feature"
  • Your PR description should have details on what the PR does. If it fixes an existing issue it should end with "Fixes #XXX".
  • When all of the tests are passing and all other conditions described herein are satisfied, a maintainer will be assigned to review and merge the PR.
  • Once you submit a PR, please do not rebase it. It's much easier to review if subsequent commits are new commits and/or merges. We squash rebase the final merged commit so the number of commits you have in the PR don't matter.
  • We expect that once a PR is opened, it will be actively worked on until it is merged or closed. We reserve the right to close PRs that are not making progress. This is generally defined as no changes for 7 days. Obviously PRs that are closed due to lack of activity can be reopened later. Closing stale PRs helps us to keep on top of all of the work currently in flight.
  • Please consider joining the envoy-dev mailing list.

PR review policy for maintainers

  • Typically we try to turn around reviews within one business day.
  • See OWNERS.md for the current list of maintainers.
  • If there is a question on who should review a PR please discuss in Slack.
  • Anyone is welcome to review any PR that they want, whether they are a maintainer or not.
  • Please clean up the title and body before merging. By default, GitHub fills the squash merge title with the original title, and the commit body with every individual commit from the PR. The maintainer doing the merge should make sure the title follows the guidelines above and should overwrite the body with the original extended description from the PR (cleaning it up if necessary) while preserving the PR author's final DCO sign-off.

DCO: Sign your work

The sign-off is a simple line at the end of the explanation for the patch, which certifies that you wrote it or otherwise have the right to pass it on as an open-source patch. The rules are pretty simple: if you can certify the contents of DCO, then you just add a line to every git commit message:

Signed-off-by: Joe Smith <[email protected]>

using your real name (sorry, no pseudonyms or anonymous contributions.)

You can add the sign off when creating the git commit via git commit -s.

If you want this to be automatic you can set up some aliases:

git config --add alias.amend "commit -s --amend"
git config --add alias.c "commit -s"

Fixing DCO

If your PR fails the DCO check, it's necessary to fix the entire commit history in the PR. Best practice is to squash the commit history to a single commit, append the DCO sign-off as described above, and force push. For example, if you have 2 commits in your history:

git rebase -i HEAD^^
(interactive squash + DCO append)
git push origin -f

Note, that in general rewriting history in this way is a hindrance to the review process and this should only be done to correct a DCO mistake.

Triggering CI re-run without making changes

To rerun failed tasks in CI, add a comment with the the line

/retest

in it. This should rebuild only the failed tasks.

Sometimes tasks will be stuck in CI and won't be marked as failed, which means the above command won't work. Should this happen, pushing an empty commit should re-run all the CI tasks. Consider adding an alias into your .gitconfig file:

[alias]
    kick-ci = !"git commit -s --allow-empty -m 'Kick CI' && git push"

Once you add this alias you can issue the command git kick-ci and the PR will be sent back for a retest.