Question

What is the best practice for pushing clean code to the main branch?

This is a best practice question about Mercurial, however the thoughts of other DVCS/git users would also be applicable. If there is a suitable website please point me to it.

How do large projects with lots of contributers keep the main development branch clean?

I pull a copy of the source from the central repository and then make a bunch of local changes using branches, tags, local merges of experimental code and commits until everything is tested and works.

Now I make the final commit and push my changes back up to the trunk – this will send the full history of my local changes to the central server.

This is conceptually fine, however that means that the supervisor who performs the final build gets to see all my experimental and buggy code working towards the final tested version.

Is there a best practice way to slim down my push so that it only contains clean code? Is it my reposonsibility to clean my code (with collapse or other extensions), or does the supervisor select the clean bits and copy them to a ‘final release’ repository?

your help is much appreciated,

Steve

=======================

Answer: I have accepted Tims answer below and the link he has given about github in particular [ github.com/git/git/blob/master/Documentation/SubmittingPatches ]. So yes – clean up your submission before pushing it to the central repository!

Answer 1

First and foremost, you need to talk to your supervisor about the expected workflow for your project. The following general advice should be good for most situations, but your project may have reasons to do things differently.

In general, you should strive to make the published history of your repository as clean as possible. Cleanliness can be judged by:

• Small, cohesive changesets
• Clean up or refactoring should be committed separately from new features.
• Each commit should pass test (to allow for tools such as bisect)

In all DVCS, there is the concept of local vs. published history. In most workflows, a changeset is considered to be published once it has been pushed to a public repository that other people have cloned.

There are two basic rules regarding editing the history of a repo:

1. Once you have published a changeset, you should not modify history. This implies that it is important to only push changesets that are ready to be published. In Mercurial terms, do not hg push all your outgoing changes. Instead, use hg push -b <branch> or hg push -r <rev> to perform a targeted push of specific changes. See EditingHistory on the Mercurial wiki for more specific reasoning and advise.

2. Before publishing changesets (i.e. while they are local), you are free to amend, rebase, collapse, etc. as needed to create a ‘clean’ history. In git, this is accomplished using git commit --amend or git rebase. Mercurial has extensions such as queues (mq), histedit and collapse.

On most projects, developers are expected to clean up their own code prior to submitting it for review and or publishing it. This saves the reviewer/integrator from wasting time on messy work.