3

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!

Steve Davies
  • 562
  • 3
  • 7
  • 14
  • 1
    is having a full history of changes not the point of VCS? I assume that on release the supervisor will just take the latest revision from the trunk and build it. – VBwhatnow Jun 26 '12 at 11:08
  • Similar to this: http://stackoverflow.com/questions/1200691/with-mercurial-how-can-i-compress-a-series-of-changesets-into-one-before-push – Alex Florescu Jun 26 '12 at 11:34
  • @AlexFlorescu and VBwhatnow - yes it is similar (that is how I found out about 'collapse') but I can't imagine the linux kernal project having every little tiny experimental change in it's main tree - surely Linus must act as an editor somehow? – Steve Davies Jun 26 '12 at 12:14
  • 1
    @VBwhatnow the OP's request makes a lot of sense. When you do a bisection, for instance, having as low a number of commit that break something (be it the build or the tests) as possible is a really, *really*, **really** nice thing. – s.m. Jun 26 '12 at 12:56

1 Answers1

5

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.

Tim Henigan
  • 60,452
  • 11
  • 85
  • 78
  • ok that makes sense, make it the contributors responsibility to make sure their code is clean and readable. So a workflow might be that you pull the main branch, play around as much as you want with multiple local branches and commits. Then to get a clean release one could re-pull the main branch to a new directory, copy over the final working code, retest and push that back to main – is that what the big open source projects do? – Steve Davies Jun 26 '12 at 13:06
  • Creating duplicate clones is probably overkill. Most of the time, you can experiment on a feature branch in your repo, modify history as needed to make it clean and push the result when done. Open source projects tend to behave differently. Few people have push access to open source repos. For projects like `git` and `mercurial`, contributors submit patches via email for review (instead of pushing). If the maintainer approves, then he will integrate the patches into restricted-access public repo. See https://github.com/git/git/blob/master/Documentation/SubmittingPatches for more info. – Tim Henigan Jun 26 '12 at 16:23
  • Tim - thank you for the link, it is what I was looking for. This sounds just like the old days of physically taking your code to the librarian on a 5" floppy disc! – Steve Davies Jun 27 '12 at 07:06