The ANTLR project is moving to github within a few days. Thanks to user anatol for setting up the ANTLR organization and pulling in the perforce (p4) repositories that we've been using. Everything is now set up for us to seamlessly start using git/github. The purpose of this blog post is to announce this move and to outline how I think workflow should go.

Repositories

Branches

I enjoyed reading A successful Git branching model and I think a lot of it makes sense for my small ANTLR team.  Basically there are 2 primary branches:

• master. This is the pristine branch on which we cut all releases. If necessary, we can make hot fixes to this branch but it should always compile and run the tests. Releases are just tags on the master branch not branches, as we did in perforce.
• dev. This branch is sort of an integration branch where all developers merge their stuff. Once the dev branch is working, we can merge it into the master to head towards a release. 

Graphically, things would look like this:

The feature branches are private branches (these do not get pushed to the github repo) where we fix bugs or create new features.

Workflow

A typical sequence would be: 

1. create branch X off of develop branch to do some work
2. do some work, committing changes to that branch all we want
3. when we are ready to merge into develop, we pull from develop in case there were any changes
4. compile in test in X branch
5. quickly merge back into develop

To cut a release, we merge develop into master in antlr/antlr4 from parrt/antlr4 or another forked repository using pull requests. When we are ready for the release, we set a tag on master. forks and clones pull to get up-to-date.

Contributions from others

Users that would like to send patches or other updates, should fork the repository, make the fix in a branch name of their choosing, and then send a pull request to antlr/*. We cannot accept anything that is not gone through our clickwrap license so for now people will have to go to that page manually and say something like "pull request xxx from user yyy" and hit submit. then I will be able to acceptable request. It is extremely important that we keep the license clean; e.g., this is why eclipse is able to include the ANTLR software.

Why are we leaving perforce?

I have enjoyed and really appreciated p4's the support of the ANTLR project for the last 10 years, but for the following reasons I'm moving to git/github (in no particular order):

• I don't want to manage a server anymore and make backups
• I don't want to have to create users to give people access to the repository; p4's open source license requires that I do not give out a single anonymous user for general access
• github's pull requests
• git's superlightweight branching that keeps the same working directory; this prevents me from having to create a new project in Intellij for each branch
• Intellij's support of perforce is nice but unbelievably slow, at least for me and the people I talk to
• Nice diff/UI at github
• Nice network effect at github and more people are familiar with git than p4

I'm leaving the p4 server running for a while until I can make sure that everything has been checked in.