Obtaining Write Access to the FreeBSD Source Tree
As more and more companies leverage FreeBSD for projects, appliances, tools and infrastructure, the question often comes up: “How can our developers gain access to FreeBSD in order to push our changes upstream?”
This document will attempt to explain the formal and informal paths that an individual must take in order to gain write or “commit” access to the FreeBSD source tree.
The following questions are answered:
- Who is granted access?
- Do you really need access?
- What general processes must be followed to gain access?
- How do I get started on the path to becoming a committer?
- What happens after committer status is granted?
- How do I maintain my committer status?
Definitions
- Contributor – an individual who is contributing code to the FreeBSD project.
- Committer – an individual with write access to the FreeBSD source repository.
- Maintainer – a committer who maintains a particular subsystem in FreeBSD.
Who is granted access?
Access can only be granted to individuals - there is no “corporate access” or “corporate account” allowed.
If an organization wishes to contribute code to FreeBSD on an ongoing basis it is essential that the individual selected by the organization have the following attributes:
- Good communication skills including patience.
- Highly skilled in the areas where contributions will be made.
- Interested in open source, preferably with some open source background already.
- Open to criticism and able to defend a technical position in a polite manner.
- Engaged in the community by participating in:
- Code.
- Project mailing lists.
- Conferences.
Without fail, it is actually the individual within the organization that shows interest who becomes a FreeBSD committer.
What general processes must be followed to gain access?
Access is granted to individuals who contribute a significant amount of code in the form of features or bug fixes. Occasionally access is granted to a technical lead that is tasked with contributing a major system such as a complex driver, file system or networking subsystem to FreeBSD.
The process to gain FreeBSD source access is a long one.
It can take months of contributions and interaction with the project before access is granted. Typically there is no formal cut-off point. Instead there is an informal continuous discussion by committers of various contributors. Those contributors that are contributing exceedingly quality code on a regular basis are eventually asked if they would like write access.
Only those that are contributing on a regular basis or have an extreme depth of knowledge of a subsystem will be asked to join the ranks of the committers.
How do I get started on the path to becoming a committer?
The best way to get started is to follow these steps:
- Subscribe to the FreeBSD mailing lists.
- Browse the Problem Report database and submit fixes to bugs or file new entries with fixes.
- Engage with the project.
- Contribute code to the project.
It is important to find the correct mailing list to discuss issues and contributions that you have.
It is considered bad form to directly email FreeBSD contributors that you do not have an existing relationship with. Please use the mailing lists.
If however there seems to be no response on the mailing lists after a few days, it may be appropriate to email the FreeBSD contributor and the mailing lists again to seek attention for your issue.
Do not engage multiple committers at the same time distinctly. This form of “shopping for a committer” or “diff shopping” is strongly frowned upon. If you are engaged with multiple FreeBSD committers, it is essential that you make each one aware of what you are doing with the others. Remember, each FreeBSD committer’s time is precious to the project, please do not waste it by trying to have more than one committer “ready” for your code at any time. You will likely find that eventually zero developers will wish to engage with you.
Also take a look at some of the first PRs current committers submitted here: HowWeGotHere.
What happens after committer status is granted?
A contributor who is invited to join the ranks of committer will have to go through a period of mentorship. The FreeBSD mentoring guide explains this process.
Remember, once access is obtained, commits still must be reviewed. It is particularly important to obtain reviews for changes to areas of code that you have not shown experience with. When in doubt, ask!
How do I maintain my committer status?
It is important that each contributor keep up to date with the direction the FreeBSD project is going, maintain familiarity with systems that they work on, and continue to contribute.
Additionally the rank of “committer” is a badge of honor worn by many FreeBSD developers and it is the collective feeling that in order to maintain “committer status” that a committer continue to contribute code to the project.
If a developer has not contributed code to the project for more than a year, they will be asked to retire their commit bit and join the ranks of FreeBSD alumni.
Retired committers are always welcome back, but it is expected that a returning committer only request re-instatement if their level of contribution will be at a level that they maintained when formerly active.
What if this “committer stuff” is too involved for me? How can I still get my code in?
That is fine, it does take quite a lot of work and time to get that involved.
The good news is that existing FreeBSD committers are usually more than happy to bring your code into FreeBSD provided you are open to code review feedback.
We strongly suggest subscribing to relevant mailing lists and making use of the problem report database to file bugs containing the code. If you can find a committer who is the maintainer or interested in bringing your code in that will be helpful. Remember: do not “shop your code” amongst multiple developers!
Summary
- Only individuals can be committers.
- It is important to maintain contact with the project through mailing lists and conferences.
- Many contributions are required before even being considered for “committer access”.
- If becoming a committer is too involved for you then just use the problem report database and the mailing lists to submit code, someone will happily pick up your changes.
- Do not shop your changes amongst multiple project members.
- Have fun, we all want to bring in your contribution.
- Do not get discouraged! FreeBSD is a volunteer project, it may require ringing the doorbell a few times before we answer the door.
We look forward to working with you.
Please also reference the Committer's Guide for actual committer rules and expectations.