We welcome contributions from the community. Please read the following guidelines carefully to maximize the chances of your PR being merged.
- 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 LOC 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.
- Specifically, if the goal is to add a new extension, please read the extension policy.
- Small patches and bug fixes don't need prior communication.
- See STYLE.md
The Envoy community has an explicit goal to be inclusive to all. As such, all PRs must adhere to the following guidelines for all code, APIs, and documentation:
- The following words and phrases are not allowed:
- Whitelist: use allowlist instead.
- Blacklist: use denylist or blocklist instead.
- Master: use primary or main instead.
- Slave: use secondary or replica instead.
- Documentation should be written in an inclusive style. The Google developer documentation contains an excellent reference on this topic.
- The above policy is not considered definitive and may be amended in the future as industry best practices evolve. Additional comments on this topic may be provided by maintainers during code review.
Both API and implementation stability are important to Envoy. Since the API is consumed by clients beyond Envoy, it has a distinct set of versioning guidelines. Below, we articulate the Envoy implementation stability rules, which operate within the context of the API versioning guidelines:
- Features may be marked as deprecated in a given versioned API at any point in time, but this may
only be done when a replacement implementation and configuration path is available in Envoy on
main. Deprecators must implement a conversion from the deprecated configuration to the latest
vNalpha
(with the deprecated field) that Envoy uses internally. A field may be deprecated if this tool would be able to perform the conversion. For example, removing a field to describe HTTP/2 window settings is valid if a more comprehensive HTTP/2 protocol options field is being introduced to replace it. The PR author deprecating the old configuration is responsible for updating all tests and canonical configuration, or guarding them with theDEPRECATED_FEATURE_TEST()
macro. This will be validated by thebazel.compile_time_options
target, which will hard-fail when deprecated configuration is used. The majority of tests and configuration for a feature should be expressed in terms of the latest Envoy internal configuration (i.e.vNalpha
), only a minimal number of tests necessary to validate configuration translation should be guarded via theDEPRECATED_FEATURE_TEST()
macro. - We will delete deprecated configuration across major API versions. E.g. a field marked deprecated in v2 will be removed in v3.
- Unless the community and Envoy maintainer team agrees on an exception, during the
first release cycle after a feature has been deprecated, use of that feature
will cause a logged warning, and incrementing the
runtime
runtime.deprecated_feature_use
stat. During the second release cycle, use of the deprecated configuration will cause a configuration load failure, unless the feature in question is explicitly overridden in runtime config (example), or ifenvoy.features.enable_all_deprecated_features
is set to true. Finally, following the deprecation of the API major version where the field was first marked deprecated, the entire implementation code will be removed from the Envoy implementation. - If the runtime key
envoy.features.fail_on_any_deprecated_feature
is enabled, use of deprecated fields will trigger a configuration load failure rather than a logged warning. - This policy means that organizations deploying main should have some time to get ready for breaking changes at the next major API version. This is typically a window of at least 12 months or until the organization moves to the next major API version.
- The breaking change policy also applies to source level extensions (e.g., filters). Code that conforms to the public interface documentation should continue to compile and work within the deprecation window. Within this window, a warning of deprecation should be carefully logged (some features might need rate limiting for logging this). We make no guarantees about code or deployments that rely on undocumented behavior. See extension removal policy for more information.
- All deprecations/breaking changes will be clearly listed in the version history.
- High risk deprecations/breaking changes may be announced to the envoy-announce email list but by default it is expected the multi-phase warn-by-default/fail-by-default is sufficient to warn users to move away from deprecated features.
-
Fork the repo.
-
In your local repo, install the git hooks that implement various important pre-commit and pre-push checks:
./support/bootstrap
Please see support/README.md for more information on these hooks.
-
Create your PR. If your PR adds new code, it should include tests covering the new code. Please note that draft PRs may not be reviewed and will likely not be triaged, so do not create your PR as a draft if you want prompt reviews!
-
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.
-
Any PR that changes user-facing behavior must have associated documentation in docs as well as release notes. API changes should be documented inline with protos as per the API contribution guidelines. If a change applies to multiple sections of the release notes, it should be noted in the first (most important) section that applies. For instance, a bug fix that introduces incompatible behavior should be noted in
Incompatible Behavior Changes
but not inBug Fixes
. -
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 commit message will be used as the commit message when your PR is merged. You should update this field if your PR diverges during review.
-
Your PR description should have details on what the PR does. If it fixes an existing issue it should end with "Fixes #XXX".
-
If your PR is co-authored or based on an earlier PR from another contributor, please attribute them with
Co-authored-by: name <name@example.com>
. See GitHub's multiple author guidance for further details. -
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 your PR is under review, please do not rebase it. If you rebase, you will need to force push to github, and github's user interface will force your reviewer to review the PR from scratch rather than simply look at your latest changes. It's much easier to review 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. Again once your PR is assigned a reviewer, unless you need to fix DCO please do not force push. If you need to pull recent changes you can run
branch=$(git status|head -1|cut -f3 -d\ ) git checkout main git pull git checkout "$branch" git merge main
-
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.
-
If a commit deprecates a feature, the commit message must mention what has been deprecated. Additionally, the version history must be updated with relevant RST links for fields and messages as part of the commit.
-
Please consider joining the envoy-dev mailing list.
-
If your PR involves any changes to envoy-filter-example (for example making a new branch so that CI can pass) it is your responsibility to follow through with merging those changes back to main once the CI dance is done.
-
If your PR is a high risk change, the reviewer may ask that you runtime guard it. See the section on runtime guarding below.
Some changes in Envoy are deemed worthy of runtime guarding. Instead of just replacing old code with new code, both code paths are supported for between one Envoy release (if it is guarded due to performance concerns) and a full deprecation cycle (if it is a high risk behavioral change). Generally as a community we try to guard both high risk changes (major refactors such as replacing Envoy's buffer implementation) and most user-visible non-config-guarded changes to protocol processing (for example additions or changes to HTTP headers or how HTTP is serialized out) for non-alpha features. Feel free to tag @envoyproxy/maintainers if you aren't sure if a given change merits runtime guarding.
The canonical way to runtime guard a feature is
if (Runtime::runtimeFeatureEnabled("envoy.reloadable_features.my_feature_name")) {
[new code path]
} else {
[old_code_path]
}
Runtime guarded features named with the "envoy.reloadable_features." prefix must be safe to flip true or false on running Envoy instances. In some situations it may make more sense to latch the value in a member variable on class creation, for example:
bool use_new_code_path_ =
Runtime::runtimeFeatureEnabled("envoy.reloadable_features.my_feature_name")
This should only be done if the lifetime of the object in question is relatively short compared to the lifetime of most Envoy instances, i.e. latching state on creation of the Http::ConnectionManagerImpl or all Network::ConnectionImpl classes, to ensure that the new behavior will be exercised as the runtime value is flipped, and that the old behavior will trail off over time.
Runtime guarded features may either set true (running the new code by default) in the initial PR, after a testing interval, or during the next release cycle, at the PR author's and reviewing maintainer's discretion. Generally all runtime guarded features will be set true when a release is cut. Old code paths for refactors can be cleaned up after a release and there has been some production run time. Old code for behavioral changes will be deprecated after six months if no Envoy operators have raised concerns. If the behavioral change is problematic for any Envoy users, the maintainers team will work to find a satisfactory resolution, generally in the form of a permanent configuration knob for the behavioral differences.
Runtime features are set true by default by inclusion in source/common/runtime/runtime_features.cc
There are four suggested options for testing new runtime features:
- Create a per-test Runtime::LoaderSingleton as done in DeprecatedFieldsTest.IndividualFieldDisallowedWithRuntimeOverride
- Create a parameterized test where the set up of the test sets the new runtime value explicitly to GetParam() as outlined in (1).
- Set up integration tests with custom runtime defaults as documented in the integration test README
- Run a given unit test with the new runtime value explicitly set true or false as done for runtime_flag_override_test
Runtime code is held to the same standard as regular Envoy code, so both the old path and the new should have 100% coverage both with the feature defaulting true and false.
Please note that if adding a runtime guarded feature, your release notes should include both the functional change, and how to revert it, for example
- area: config
change: |
type URL is used to lookup extensions regardless of the name field. This may cause problems for empty filter configurations or mis-matched protobuf as the typed configurations. This behavioral change can be temporarily reverted by setting runtime guard ``envoy.reloadable_features.no_extension_lookup_by_name`` to false.
- Typically we try to turn around reviews within one business day.
- See OWNERS.md for the current list of maintainers.
- It is generally expected that a senior maintainer should review every PR to core code. Changes which only touch tests, extensions, tools, docs or comments need only be reviewed by a maintainer, or senior extension maintainer.
- It is also generally expected that a "domain expert" for the code the PR touches should review the PR. This person does not necessarily need to have commit access.
- For new extensions (contrib or otherwise) and features, at least one of the approvals should be from an organization different from the PR author. E.g., if Lyft authors a PR, at least one approver should be from an organization other than Lyft. This helps us make sure that we aren't putting organization specific shortcuts into the code. new HTTP/3 features are largely exempt from cross-company approvals as all of the area experts work at a single company, but HTTP/3 changes which impact general functionality still merit a cross-company check.
- contrib extensions do not need senior maintainer or maintainer review only contrib owner review and a maintainer stamp to merge.
- 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 make sure that the PR title, commit message, and description are updated if the PR changes significantly during review.
- 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 commit message from the PR (cleaning it up if necessary) while preserving the PR author's final DCO sign-off.
- If a PR includes a deprecation/breaking change, notification should be sent to the envoy-announce email list.
If you change anything in the api tree, please read the API Review Checklist and make sure that your changes have addressed all of the considerations listed there.
For developers adding a new extension, one can take an existing extension as the starting point.
Extension configuration should be located in a directory structure like
api/envoy/extensions/area/plugin/
, for example api/envoy/extensions/access_loggers/file/
The code for the extension should be located under the equivalent
source/extensions/area/plugin
, and include an envoy_cc_extension with the
configuration and tagged with the appropriate security posture, and an
envoy_cc_library with the code.
More details on how to add a new extension API can be found here:
See EXTENSION_POLICY.md for more information on contrib. Adding a contrib extension mostly mirrors adding a normal extension above. Some differences are noted here:
- API files should be added in
api/contrib/envoy/
, but the protos' namespaces should still be as in normal extensions (which will make file movement easier later if the extension gets promoted to core). - Build config and metadata should be included in contrib/contrib_build_config.bzl and contrib/extensions_metadata.yaml.
- An entrypoint should be added in
docs/root/api-v3/config/contrib/contrib.rst
Envoy ships commit hooks that allow you to auto-generate the DCO signoff line if
it doesn't exist when you run git commit
. Simply navigate to the Envoy project
root and run:
./support/bootstrap
From here, simply commit as normal, and you will see the signoff at the bottom of each commit.
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 below (from developercertificate.org):
Developer Certificate of Origin
Version 1.1
Copyright (C) 2004, 2006 The Linux Foundation and its contributors.
660 York Street, Suite 102,
San Francisco, CA 94110 USA
Everyone is permitted to copy and distribute verbatim copies of this
license document, but changing it is not allowed.
Developer's Certificate of Origin 1.1
By making a contribution to this project, I certify that:
(a) The contribution was created in whole or in part by me and I
have the right to submit it under the open source license
indicated in the file; or
(b) The contribution is based upon previous work that, to the best
of my knowledge, is covered under an appropriate open source
license and I have the right under that license to submit that
work with modifications, whether created in whole or in part
by me, under the same open source license (unless I am
permitted to submit under a different license), as indicated
in the file; or
(c) The contribution was provided directly to me by some other
person who certified (a), (b) or (c) and I have not modified
it.
(d) I understand and agree that this project and the contribution
are public and that a record of the contribution (including all
personal information I submit with it, including my sign-off) is
maintained indefinitely and may be redistributed consistent with
this project or the open source license(s) involved.
then you just add a line to every git commit message:
Signed-off-by: Joe Smith <joe@gmail.com>
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"
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.
To rerun failed tasks in Azure pipelines, add a comment with 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.
Contributors with push-access to the Envoy project should prefer pushing changes to a personal fork, including when creating branches for pull requests.
This helps keep the Envoy repo as lean as possible, which can speed up cloning and synchronizing operations for both developers and CI.