Guide for new project committers
Here's how to set up the technical and social environment that will support your work as a committer to an Apache project. Some projects have more specific guidelines which the project website or the PMC provide for you. We also have a thorough Committers' FAQs for both new and experienced committers.
- What is a committer?
- Becoming a committer
- Committer resources
- The Apache Community
- Committer responsibilities
- Attending ApacheCon
- Personal web space
- Identity theft
- Share your wisdom
- The last word
What is a committer?¶
The plain sense of the word "committer" is that you have access rights to your project's repository so you can read and write the source code. Rather than creating a patch and submitting it to be actively reviewed and then committed, you can now create a local patch and commit it yourself - or even review and commit patches created by others. Your fellow committers will review your patches, usually after you commit them.
Becoming a committer¶
If you are not yet a committer, but would like to become one, review:
The Committer's Way¶
As a committer, you have access to a specific Apache project's repository so you can create and edit source code files, not just read them. Instead of having to create and submit a patch which other committers would have to review and approve, you can now create a local patch and commit it yourself; you can also review and commit patches that other project contributors and committers create. Your patches can still be reviewed by your fellow committers.
Some projects use RTC (Review then Commit) rather than CTR (Commit then Review). Check which pattern your project uses, and then follow it.
Take more care than you may have done before when working on the code, since you can now change things directly, without review. Make sure you understand how your project's committers work and coordinate with each other. Ask your project PMC, or any active committer on the project, for guidance if there are things you are not sure about. In general, the more visible and engaged you are in the project, the more fun you will have and the more access you will have to advice and feedback.
Submitting your Individual Contributor License Agreement (ICLA)
If you are a brand-new committer, you must complete and submit an Individual Contributor License Agreement (ICLA) before the ASF can activate your committer account. Note that an account can only be created if a PMC (or Incubator podling) has invited you. The ICLA is a formal contract that declares the terms under which you will contribute intellectual property to the ASF. Note that the ICLA does not assign copyright to the ASF; you retain copyright to your own work. However it does grant the ASF sufficient rights to release any work you submit under the Apache license.
- Choose an Apache ID before submitting your ICLA. Also select an alternative, in case the ID you want is unsuitable or already taken. Your ID must consist of at least three lower-case alphanumeric characters, starting with a letter. (This list shows the IDs that are already taken.)
- Identify your project (PMC or incubator podling).
- IMPORTANT: you may need to hold discussions with your employer before signing the ICLA, since your employer may have rights to the coding work you do, even outside of your employment. Your employer might even need to provide a Corporate CLA - determining that is your responsibility. Make sure that you keep up-to-date with this requirement.
- Read and understand the agreements ICLA specifies and strive to meet the standards expected. Correct title to code sources is of great importance to ASF and it must be to you, too.
- Make sure that any code you contribute is original work, and that you publicly contribute it to the ASF. In the case of any doubt (or when a contribution has a complex history) please consult your project PMC before committing it.
Some procedures may appear a little bureaucratic, but they are there to protect you as well as ASF. For a clearer understanding read the ASF license guide.
For details on how to submit your ICLA, please see Submitting License Agreements. Make sure you fill out the ICLA clearly. To minimize the chance of typographical errors, submit the ICLA as an attachment to an email you send from the email address you provide in the ICLA.
Acceptance of your ICLA¶
After the ASF Secretary records your ICLA, your PMC can submit your requested ID for activation. The acceptance process may take some time. The ASF will inform you and your PMC chair when the process is complete. This quiet lull is a good time to familiarize yourself with the Apache Software Foundation in general. Browse the developer guides and information, material about the ASF infrastructure, and the Foundation website. We update the websites regularly.
You will also need to familiarize yourself with some Apache policies and procedures. You have probably picked up a lot of this by osmosis already, and your fellow committers and PMC members on your project's
dev@ mailing list are the first place to ask questions.
Key Committer resources:
- ASF Developer Guides & Resources contains pointers to the most important information
- the ASF How it works document
- the Apache Training (Incubating) pages
- the ASF Bylaws
Apache Committer account creation¶
You will receive an email when your account has been created. (This may take a week or two.) It is now time to do several general tasks, and possibly take some other steps specific to your project that your PMC will share with you.
Set up your `@apache.org` email address¶
Read the guide to connecting to and working with your Apache email inbox.
Record any email aliases you use in the
asf-altEmail field in your LDAP record. You can do this through the the self-serve application. The system uses the address in the LDAP
@apache.org address. This field must have at least one entry, which must not be your
asf-altEmail field is used to validate subscription requests and correlate subscriptions. (There is no need to duplicate
Note: Please read Dealing with spam in your ASF email account and do not flag valid ASF-related email as spam.
Set up Subversion or Git access¶
Read about source control repositories at Apache.
Configure your access to project Git repositories¶
If your project uses Git to store, develop, and deploy its product code, you can use either GitHub or Apache's Gitbox for actions such as merging pull requests.
To use GitHub, you need to integrate your GitHub ID with your Apache account, so that you can merge pull requests and perform other Git tasks.
- Verify you have a GitHub ID enabled with two factor authentication (2FA).
- Merge your Apache and GitHub accounts using Boxer, the Apache account linking utility for GitHub. Follow the steps outlined in the linking process. You should see three green checks in Boxer when your account has been fully linked.
- After about two to five minutes, you should have access to your project's repositories on GitHub.
To connect to Git repositories through Gitbox, visit Gitbox and follow the onscreen instructions.
Your first commit to a Git repository
If your project has a page for its developers and committers on its website, add your name and information to it. This is a great way to make your first commit, and helps your team get to know you.
It also serves another purpose: you will learn how to add documentation to your project's website and the technology used to build it. Documentation is vital, and being able to improve the project's web site is a skill that you will need. If your project has not documented how to rebuild the website, then ask on your
dev@ mailing list and use the answer to create a document describing how to do that. It will be gratefully received!
Every team has a lot of "tribal knowledge" that team members hold in their heads or in private notes, but that the whole team needs to know in order to function well and survive a disaster like a key team member suddenly becoming unavailable. You can help migrate tribal knowledge into the documentation, by noting where you have to ask a team member for guidance that you cannot find in the docs.
Set Up Security And PGP Keys¶
Security is vital and Apache pays great attention to it. Remember that at all times, and ensure that all your Apache passwords are sufficiently secure, and that any code you check in is safe.
OpenPGP is a standard that provides (among other things) methods to create digital signatures for documents ranging from emails to ASF releases. Many applications provide OpenPGP compatible signatures, including the well-known GPG. We recommend that you create a PGP key for your
apache.org address (or add that address to an existing key). DO NOT create this key on any machine to which many users have access and DO NOT ever copy your private key to any other shared machine. Release managers need to take particular care of keys used to sign releases.
Upload the public key to a public key server, for example the MIT PGP Public Key Server. Then add your keys' primary fingerprints to your LDAP profile. The system adds your key to the individual and per-project pre-fetched KEYS files, and lets automated tools encrypt communications to you.
Start to build up a good web of trust now before you need to use it in earnest. Be prepared to exchange key information at face-to-face events where ASF folks may be present. The best practice is to insist on identification before signing another person's key. See the Apache release signing guide.
The Infra documentation page provides a list of resources for committers and other Apache folks.
Check out the Committers-only Subversion module¶
Do a checkout of the private
committers module. This is stored in the subversion repository at
https://svn.apache.org/repos/private/committers. See Subversion basics if you are unfamiliar with Subversion.
Once you have checked out this module, read all the documents contained in the
docs directory, especially the
resources.txt file. There are a number of private mailing lists you need to know about. Join in the Apache community by signing up to every list that interests you. It is better to sign up (even if you sign off later) than to miss out! Please respect the usage guidelines for these private lists.
Get to know the Apache community¶
Taking part in the community makes Apache fun. The Community Development project has a central mailing list for topics that cut across PMC boundaries. Discussions of all kinds are on topic as long as the matter is not sensitive or confidential.
Join email lists¶
A lot of Apache knowledge-sharing and all formal decision-making takes place on email lists. Most of the lists are public, and you can join and participate in any that attract you.
- Your project probably has a
users@email list, and it is a good idea to join both.
- We strongly urge all committers to join the
builds@email list, where people from many projects, and the Infrastructure team, share insights and solve problems related to building and releasing software packages. People using Jenkins, or interested in CI/CD (continuous intergration and continuous development) find this list invaluable. Infra also posts notifications to this list regarding outages, upgrades, app add/removals and more.
Instructions for joining and leaving lists, and a browsable list of Apache mailing lists, are here.
Join your project's
dev@ mailing lists to keep up with project activity. Answering questions on
users@ is also very much appreciated and noticed by your PMC.
Each committer has a responsibility to monitor changes made for potential issues, both coding and legal. If you spot any potential issues in a commit, the right course of action is to post a reply (to the email) raising your concerns to the
dev@ list. In extreme situations, it may be necessary to veto (-1) a commit, but this is an extreme sanction and rarely warranted. Read the voting guidelines before deploying a veto.
Do not be surprised if your first commit has a delayed diff email. It needs to go through the human moderators.
If you do not have one already, make a note in your diary about the next ApacheCon. This is a great opportunity to meet other Apache folks, hack code and learn about great new open source projects. Watch the lists as the conference dates approach for details about special deals for committers and opportunities to speak.
Personal web space¶
Some Apache committers have personal content served from ASF web servers. There are no fixed guidelines about appropriate content: committers should know how to behave! In general, people use this option to host ASF-related content or to showcase interesting private projects. If you do use this feature, please do so responsibly.
Material placed in the
public_html directory is available under the
http://home.apache.org/~username/ url (where username is your ASF account ID).
Please be aware that Apache Software Foundation committers are targets for identity theft. These spoof attacks resemble phishing attacks used to gain access to bank accounts and other web subscriptions. They typically seek to persuade you to enter your access details into a fake website. The ASF will never solicit such 'verification'.
Leaking your access to Apache can have very destructive consequences. Never disclose your ASF password to anyone.
The Apache Infrastructure team is clueful about DNS maintenance: do not trust any redirection by IP address. Your access to Apache will be through the
machines serving the
svn.apache.org domain. The SSH/SSL fingerprints of machines are listed on the machines page, and our SVN server fingerprints are also listed.
Please use caution. Do not hesitate to ask if you have doubts: post a question to infrastructure before taking any action.
Share your wisdom¶
Volunteer if you would like to help the Infrastructure team keep the good ship ASF afloat.
The last word