First, thank you for contributing to Vector! The goal of this document is to provide everything you need to start contributing to Vector. The following TOC is sorted progressively, starting with the basics and expanding into more specifics. Everyone from a first time contributor to a Vector team member will find this document useful.
- You're familiar with Github and the pull request workflow.
- You've read Vector's docs.
- You know about the Vector community. Please use this for help.
- Ensure your change has an issue! Find an
existing issue or open a new issue.
- This is where you can get a feel if the change will be accepted or not.
Changes that are questionable will have a
needs: approvallabel.
- This is where you can get a feel if the change will be accepted or not.
Changes that are questionable will have a
- Once approved, fork the Vector repository in your own Github account (only applicable to outside contributors).
- Create a new Git branch.
- Review the Vector change control and development workflows.
- Make your changes.
- Submit the branch as a pull request to the main Vector repo. A Vector team member should comment and/or review your pull request within a few days. Although, depending on the circumstances, it may take longer.
If you're contributing a new source, sink, or transform to Vector, thank you that's way cool! There's a few steps you need think about if you want to make sure we can merge your contribution. We're here to help you along with these steps but they are a blocker to getting a new integration released.
To merge a new source, sink, or transform, you need to:
- Add tests, especially integration tests if your contribution connects to an external service.
- Add instrumentation so folks using your integration can get insight into how it's working and performing. You can see some example of instrumentation in existing integrations.
- Add documentation. You can see examples in the
docsdirectory.
All changes must be made in a branch and submitted as pull requests. Vector does not adopt any type of branch naming style, but please use something descriptive of your changes.
Please ensure your commits are small and focused; they should tell a story of your change. This helps reviewers to follow your changes, especially for more complex changes.
Your commits must include a DCO signature. This is simpler than it sounds; it just means that all of your commits must contain:
Signed-off-by: Joe Smith <[email protected]>
Git makes this easy by adding the -s or --signoff flags when you commit:
git commit -sm 'My commit message'We also included a make signoff target that handles this for you if
you forget.
Once your changes are ready you must submit your branch as a pull
request.
The pull request title must follow the format outlined in the conventional
commits spec.
Conventional commits is a standardized
format for commit messages. Vector only requires this format for commits on
the master branch. And because Vector squashes commits before merging
branches, this means that only the pull request title must conform to this
format. Vector performs a pull request check to verify the pull request title
in case you forget.
A list of allowed sub-categories is defined here.
The following are all good examples of pull request titles:
feat(new sink): new `xyz` sink
feat(tcp source): add foo bar baz feature
fix(tcp source): fix foo bar baz bug
chore: improve build process
docs: fix typos
All pull requests should be reviewed by:
- No review required for cosmetic changes like whitespace, typos, and spelling by a maintainer
- One Vector team member for minor changes or trivial changes from contributors
- Two Vector team members for major changes
- Three Vector team members for RFCs
If there are any reviewers assigned, you should also wait for their review.
All pull requests are squashed and merged. We generally discourage large pull requests that are over 300-500 lines of diff. If you would like to propose a change that is larger we suggest coming onto our Discord server and discuss it with one of our engineers. This way we can talk through the solution and discuss if a change that large is even needed! This will produce a quicker response to the change and likely produce code that aligns better with our process.
Currently Vector uses Github Actions to run tests. The workflows are defined in
.github/workflows.
Github Actions is responsible for releasing updated versions of Vector through various channels.
Tests are run for all changes except those that have the label:
ci-condition: skip
Some long running tests are only run daily, rather than on every pull request. If needed, an administrator can kick off these tests manually via the button on the nightly build action page
Historically, we've had some trouble with tests being flakey. If your PR does not have passing tests:
- Ensure that the test failures are unrelated to your change
- Is it failing on master?
- Does it fail if you rerun CI?
- Can you reproduce locally?
- Find or open an issue for the test failure (example)
- Link the PR in the issue for the failing test so that there are more examples
You can invoke the test harness by commenting on any pull request with:
/test -t <name>As discussed in the README, you should continue to the following
documents:
- DEVELOPING.md - Everything necessary to develop
- DOCUMENTING.md - Preparing your change for Vector users
To protect all users of Vector, the following legal requirements are made. If you have additional questions, please contact us.
Vector requires all contributors to agree to the DCO. DCO stands for Developer Certificate of Origin and is maintained by the Linux Foundation. It is an attestation attached to every commit made by every developer. All contributions are covered by, and fall under, the DCO.
Trivial changes, such as spelling fixes, do not need to be signed.
This is covered by the DCO. Contributions are covered by the DCO and do not require a CLA.
It's simpler, clearer, and still protects users of Vector. We believe the DCO more accurately embodies the principles of open-source. More info can be found here:
Nope! The DCO confirms that you are entitled to submit the code, which assumes that you are authorized to do so. It treats you like an adult and relies on your accurate statement about your rights to submit a contribution.
No problem! We made this simple with the signoff Makefile target:
make signoffIf you prefer to do this manually:
git commit --amend --signoff