Celebrating 20 years of community-led development "The Apache Way"
This Guide for New Committers is meant to provide an introduction to setting up various technical and social bits that are useful for people who have been granted committer access to an Apache project. These are general tips or for procedure used by most Apache projects, however some projects have more specific guidelines which should be covered by their website or provided by the PMC member(s) who invited the new committer to their specific project. We also have a thorough Committers' FAQ for already established committers.
To find out how to become a committer, please read:
The plain sense of the word "committer" is that you will have access rights to a specific Apache project's repository to write (as well as read) the source. Rather than creating a patch and submitting it to be actively reviewed and then (hopefully) committed, you can now create a local patch and commit it yourself - or even review and commit patches created by others. Your patches will still be reviewed by your fellow committers. Note that some projects use RTC (Review then Commit) rather than CTR (Commit then Review). Please check first.
Take more care than you did before when working on the code, since you can change things directly. You should already know well (by example) how committers on your project are expected to behave. If you are not familiar, you can always ask your PMC for guidance.
If you are a brand new committer, you must first to complete and submit an Individual Contributor License Agreement (ICLA) before your committer account will be activated. This 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.
For details on specifically how to submit your ICLA, please see Submitting License Agreements. Please ensure that it is clearly written. In order to minimize typographical errors, it is best to send the ICLA in an email attachment from the email address on the ICLA.
Please choose an Apache id before submitting your ICLA. Please think also of an alternative, in the case that the primary is unsuitable or taken. Note that your id must consist of at least 3 lower-case alphanumeric characters, starting with a letter. (This list shows the ids that already taken). Be sure to identify the project (PMC or incubator podling) on your ICLA before submitting it.
IMPORTANT: Note that 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. Also make sure that you keep up-to-date with this requirement.
It is important to read and understand the agreements and strive to meet the standards expected. Correct title to the source is of great importance to ASF and it must be to you too. 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.
Please take care to ensure that patches are original works which have been clearly contributed to the ASF in public. In the case of any doubt (or when a contribution with a more complex history is presented) please consult your project PMC before committing it.
Committer accounts will not be created until your ICLA has been recorded by the ASF Secretary, and your PMC can then submit your requested ID for activation. Note that an account can only be created if a PMC (or Incubator podling) has invited you. Please ensure that the ICLA records the name of the PMC that invited you, as well as a suggested login id.
The acceptance process may take some time. Please be patient. You will be informed when the process is complete (and your PMC chair will monitor the progress).
This quiet lull is a good time to familiarize yourself with the Apache Software Foundation in general. Browse the developer guides and information and the Foundation website. Remember, that the website is being continually updated, so you should regularly visit these pages.
You will also need to familiarize yourself with some Apache policies and procedures. Do not worry, this isn't as intimidating as it seems: you will probably have learnt a lot 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 Incubator Learn pages
the ASF Bylaws
You will receive an email when your account has been created. (This may take a week or two.)
There are a number of general things you need to do. These will be covered in separate sections below. There may some other things that the particular project requires, but you should be told of those by your fellow committers.
While in the past the ASF had some central servers that offered SSH logins, these have been deprecated for security purposes. There are some project-specific services that still offer SSH shells or VMs, and this is a general guide. We are not going to describe how to use ssh (there are plenty of good tutorials elsewhere). Important: the first time you login you may need to validate the host public keys.
To use key-based login, you need to generate a key on your local desktop (do not use a publicly accessible server for this) and then add your public key to LDAP using the self-service app at https://id.apache.org
Once you have done this, wait at least 10 mins. You should then be able to login as follows:
:::shell $ ssh [username]@$project-vm.apache.org
Depending on your client setup, you may need to run the following command to ensure the key(s) are made available to the ssh client on your system:
:::shell $ ssh-add
If you use PuTTY then ensure that it is configured to force SSH v2 protocol. And use keyboard-interactive.
Once you are logged on, there are few tasks best performed right away. Please take care when using your shell account.
You need to check that your
umask is set in a group friendly fashion.
This ensures that the documents you create are editable by your fellow
committers. To do this, (depending on which shell you use) edit the
.cshrc file or
.profile (sh derivatives) and ensure that the
is set as follows:
You may find that a
umask line already exists, in which case
it should be modified. Otherwise, a new line needs to be added. (You will
need to use a *nix command-line editor such as
vi.) Tip: You can view the
files of some other committer, e.g.
ls -al ~mymentor; cat
Read the Apache.org Email Setup Guide.
Please remember to record any email aliases in the 'asf-altEmail' field in your LDAP record using the self-serve application at https://id.apache.org/.
The LDAP 'mail' field is used to forward mails sent to your @apache.org address. It must have at least one entry (which must not be your @apache.org address).
The 'asf-altEmail' field is used to validate subscription requests and correlate subscriptions. (There is no need to duplicate 'mail' entries in 'asf-altEmail'.)
Read the Version Control Setup Guide.
If your project has a page about the developers and committers, go right ahead and add your name and information to it! Really. This is a great way to make your first commit.
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!
Many Apache projects use the centralized Apache CMS system to update their websites. If your project uses a different system (for example Maven or Forrest), your PMC will provide details.
Security is vital and Apache pays great attention to it. Please remember that at all times, and ensure both all your Apache passwords are sufficiently secure, as well as ensuring any code you checkin is safe.
OpenPGP is a standard which provides (amongst other things) methods to create digital signatures for documents. These documents could be emails or could be ASF releases. A variety of applications exist which provide OpenPGP compatible signatures including the well known GPG and PGP.
It is recommended that you create a PGP key for your
apache.org address now
(or add that address to an existing key, if you have one). DO NOT create
this key on any machine to which multiple
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 MIT). Afterwards, add your keys' primary fingerprints to your LDAP profile; this will cause your to be added to the individual and per-project pre-fetched KEYS files on https://home.apache.org/keys/, and allow automated tools to 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 any face-to-face events where ASF folks may be present. The best practice is to insist on identification before signing another's key. See signing guide and Henk's Key Signing HOWTO.
The Whimsy project provides a number of other committer-specific tools for finding information about Apache people.
Although the Apache Way is to keep things as public as possible, there are some resources here at Apache which are considered private to just committers; please treat this information with respect.
You should do a checkout of the private
committers module. This is stored
in the subversion repository with url
notes for those unfamiliar with subversion.)
Once you have checked out this module, you need to 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.
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 doesn't need to be sensitive or confidential.
Apache Labs is a place for innovation where committers of the foundation can experiment with new ideas. The aim is to provide the necessary resource to promote and maintain the innovative power within the Apache community without the burden of community building.
If you have an idea that you want to explore and collaborate on with other committers then come and discuss it at Labs. Even if you don't have anything at the moment, then come and take a look at what other committers are working on.
Join your project's commit@ and dev@ mailing lists to keep up with activity on your project. Answering questions on users@ is also very much appreciated and noticed by your PMC.
Each committer has a responsibility to monitor the 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 please beware that this is an extreme sanction and rarely warranted; read the voting guidelines before 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 don't 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 dream 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.
You might already be aware that some Apache folks have content served from Apache web servers. For example, Henk and Vadim both provide statistics. There are no fixed guidelines about appropriate content: committers should know how to behave! Most other folks use it for Apache related content and some for interesting private projects. If you do use it, please use it responsibly.
Material placed in the
public_html directory will be available under
username is your ASF account Id).
Please be aware that Apache Software Foundation committers are targets for identity theft. These spoof attacks resemble the 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 foundation 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 servers 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.
If you like, get involved with unofficial resources open to ASF committers:
Please help to improve this document (see guidelines for updating this website). Subscribe to the Infrastructure list if you want to discuss the improvements, or just to find out how the good ship Apache is kept afloat (and to help). Welcome!