Keep not only your project's source code under version control, but also its web pages, documentation, FAQ, design notes, and anything else that people might want to edit. Keep them right next to the source code, in the same repository tree. Any piece of information worth writing down is worth versioning—that is, any piece of information that could change. Things that don't change should be archived, not versioned. For example, an email, once posted, does not change; therefore, versioning it wouldn't make sense (unless it becomes part of some larger, evolving document).

The reason versioning everything together in one place is important is so people only have to learn one mechanism for submitting changes. Often a contributor will start out making edits to the web pages or documentation, and move to small code contributions later, for example. When the project uses the same system for all kinds of submissions, people only have to learn the ropes once. Versioning everything together also means that new features can be committed together with their documentation updates, that branching the code will branch the documentation too, etc.

Don't keep generated files under version control. They are not truly editable data, since they are produced programmatically from other files. For example, some build systems create configure based on the template configure.in. To make a change to the configure, one would edit configure.in and then regenerate; thus, only the template configure.in is an "editable file." Just version the templates—if you version the result files as well, people will inevitably forget to regenerate when they commit a change to a template, and the resulting inconsistencies will cause no end of confusion.^[18]

The rule that all editable data should be kept under version control has one unfortunate exception: the bug tracker. Bug databases hold plenty of editable data, but for technical reasons generally cannot store that data in the main version control system. (Some trackers have primitive versioning features of their own, however, independent of the project's main repository.)

The project's repository should be browsable on the Web. This means not only the ability to see the latest revisions of the project's files, but to go back in time and look at earlier revisions, view the differences between revisions, read log messages for selected changes, etc.

Browsability is important because it is a lightweight portal to project data. If the repository cannot be viewed through a web browser, then someone wanting to inspect a particular file (say, to see if a certain bugfix had made it into the code) would first have to install version control client software locally, which could turn their simple query from a two-minute task into a half-hour or longer task.

Browsability also implies canonical URLs for viewing specific revisions of files, and for viewing the latest revision at any given time. This can be very useful in technical discussions or when pointing people to documentation. For example, instead of saying "For tips on debugging the server, see the www/hacking.html file in your working copy," one can say "For tips on debugging the server, see http://subversion.apache.org/docs/community-guide/," giving a URL that always points to the latest revision of the hacking.html file. The URL is better because it is completely unambiguous, and avoids the question of whether the addressee has an up-to-date working copy.

Some version control systems come with built-in repository-browsing mechanisms, while others rely on third-party tools to do it. Three such tools are ViewCVS (http://viewcvs.sourceforge.net/), CVSWeb (http://www.freebsd.org/projects/cvsweb.html), and WebSVN (http://websvn.tigris.org/). The first works with both CVS and Subversion, the second with CVS only, and the third with Subversion only.

Every commit to the repository should generate an email showing who made the change, when they made it, what files and directories changed, and how they changed. The email should go to a special mailing list devoted to commit emails, separate from the mailing lists to which humans post. Developers and other interested parties should be encouraged to subscribe to the commits list, as it is the most effective way to keep up with what's happening in the project at the code level. Aside from the obvious technical benefits of peer review (see “Pratique uma Revisão de Código Visível”), commit emails help create a sense of community, because they establish a shared environment in which people can react to events (commits) that they know are visible to others as well.

The specifics of setting up commit emails will vary depending on your version control system, but usually there's a script or other packaged facility for doing it. If you're having trouble finding it, try looking for documentation on hooks, specifically a post-commit hook, also called the loginfo hook in CVS. Post-commit hooks are a general means of launching automated tasks in response to commits. The hook is triggered by an individual commit, is fed all the information about that commit, and is then free to use that information to do anything—for example, to send out an email.

With pre-packaged commit email systems, you may want to modify some of the default behaviors:

Non-expert version control users are sometimes a bit afraid of branching and merging. This is probably a side effect of CVS's popularity: CVS's interface for branching and merging is somewhat counterintuitive, so many people have learned to avoid those operations entirely.

If you are among those people, resolve right now to conquer any fears you may have and take the time to learn how to do branching and merging. They are not difficult operations, once you get used to them, and they become increasingly important as a project acquires more developers.

Branches are valuable because they turn a scarce resource—working room in the project's code—into an abundant one. Normally, all developers work together in the same sandbox, constructing the same castle. When someone wants to add a new drawbridge, but can't convince everyone else that it would be an improvement, branching makes it possible for her to go to an isolated corner and try it out. If the effort succeeds, she can invite the other developers to examine the result. If everyone agrees that the result is good, they can tell the version control system to move ("merge") the drawbridge from the branch castle over to the main castle.

It's easy to see how this ability helps collaborative development. People need the freedom to try new things without feeling like they're interfering with others' work. Equally importantly, there are times when code needs to be isolated from the usual development churn, in order to get a bug fixed or a release stabilized (see “Stabilizing a Release” and “Maintaining Multiple Release Lines” in Capítulo 7, Packaging, Releasing, and Daily Development) without worrying about tracking a moving target.

Use branches liberally, and encourage others to use them. But also make sure that a given branch is only active for exactly as long as needed. Every active branch is a slight drain on the community's attention. Even those who are not working in a branch still maintain a peripheral awareness of what's going on in it. Such awareness is desirable, of course, and commit emails should be sent out for branch commits just as for any other commit. But branches should not become a mechanism for dividing the development community. With rare exceptions, the eventual goal of most branches should be to merge their changes back into the main line and disappear.

Merging tem um corolário importante: nunca comite a mesma mudança duas vezes. Isto é, uma mudança deve entrar no sistema de controle de versionamento exatamente uma única vez. A revisão (ou conjunto de revisões) na qual a mudança foi efetuada é o seu único identificador. Caso seja necessária a sua efetuação em uma branch diferente da que foi feita, então ela deve ser merged do seu ponto de criação original para os outros pontos de destino —ao contrário de comitar uma mudança textualmente idêntica, que teria o mesmo efeito no código, mas tornaria impossíveis a precisão de estruturação e o gerenciamento de releases.

Os efeitos práticos desta recomendação variam de um sistema de controle de versão para o outro. Em alguns sistemas, merges são eventos especiais, distintos de commits, e têm seus proprios metadados. Em outros, os resultados de merges são comitados da mesma forma que outras mudanças são comitadas, então o principal modo de diferenciar um "merge commit" de um "commit de novas mudanças" é a log message. Na log message de um merge, não repita a mesma existente na mudança original. Ao contrário, apenas indique que está sendo realizado um merge, e forneça a revisão que contenha a mudança original, com um sumário de no máximo uma frase do que ela faz. Se alguém quiser ler a mensagem completa, deverá então consultar a revisão original.

A razão da importância de se evitar a repetição da log message é que, às vezes, elas são modificadas após serem comitadas. Se a log message de uma mudança fosse repetida a cada efetuação de merge, então até se alguém editasse a mensagem original, ainda seria necessário atualizar todas as repetições—o que causaria um monte de confusão.

O mesmo princípio se aplica para reverter uma mudança. Se uma mudança é retirada do código, a log message da reversão deve apenas indicar, especificamente, qual é a revisão (ou revisões) que está sendo revertida, e não descrever a mudança gerada no arquivo derivada da reversão, uma vez que a semântica da mudança pode ser obtida através da leitura da log message original. É claro que a log message da reversão deve indificar a razão pela qual a mudança está sendo revertida, mas ela não deve conter duplicações derivadas da log message original. Se possível, volte e edite a log message original para evidenciar o que foi revertido.

Tudo dito acima significa que você deve usar uma sintaxe consistente quando se referir a revisões. Isto é útil não somente em log messages, mas também em emails, no bug tracker, e em todos os outros lugares. Se você está usando CVS, sugiro "path/to/file/in/project/tree:REV", onde REV é um número de revisão no CVS, como "1.76". Se você está usando Subversion, a sintaxe padrão para a revisão 1729 é "r1729" (endereços de arquivos não são necessários por que o Subversion usa números de revisão globais). Em outros sistemas, normalmente há uma sintaxe padrão para expressar o nome das alterações. Seja qual for a sintaxe apropriada para o seu sistema, estimule as pessoas a usá-la quando forem aplicar mudanças. Uma nomeação de mudanças consistente facilita a estruturação do projeto (como veremos em Capítulo 6, Communications e Capítulo 7, Packaging, Releasing, and Daily Development), e como muita da estruturação será feita por voluntários, se torna necessário deixá-la o simples possível.

Veja também “Releases and Daily Development” em Capítulo 7, Packaging, Releasing, and Daily Development.

A maioria dos sistemas de controle de versão oferecem uma funcionalidade para que certas pessoas sejam autorizadas ou não a comitar em sub-áreas do repositório. Seguindo o princípio de que quando na posse de um martelo as pessoas começam a procurar por pregos, muitos projetos usam esta funcionalidade com vigor, garantindo cuidadosamente acesso às pessoas apenas para as áreas as quais foram aprovadas a comitar, e certificando-se de que elas não podem comitar em nenhum outro lugar. (Veja “Committers” em Capítulo 8, Managing Volunteers para ver como é decidido quem pode comitar aonde.)

Provavelmente poucos danos ocorrerão com o uso de um controle tão rigoroso, no entanto uma política mais descontraída também é aceita. Alguns projetos simplesmente usam um sistema de honra: quando uma pessoa é autorizada a comitar, até para uma sub-área do repositório, o que ela recebe, na verdade, é uma senha que a possibilita comitar em qualquer lugar do projeto. Só lhe é pedido que mantenha os seus commits na área determinada. Lembre-se que na verdade não há nenhum risco aqui: em um projeto ativo, todos os commits são revisados, de qualquer modo. Se alguém ver um commit onde não deveria estar, isto será percebido e então será falado algo. Se uma mudança precisar ser desfeita, isto é muito simples —tudo está sob versionamento de controle mesmo, então é só reverter.

Existem diversas vantagens à abordagem mais descontraída. Primeiro, como desenvolvedores evoluem para outras áreas (o que provavelmente acontecerá caso eles continuem no projeto), não haverá sobrecarga administrativa para garantir maiores privilégios. Uma vez tomada a decisão, a pessoa pode começar a comitar na nova área imediatamente.

Em segundo lugar, a expansão pode ser feita de um modo mais refinado. Geralmente, um committer na área X que quer evoluir para a área Y começará a enviar patches para a área Y e pedir por review. Se alguém que já tem permissão a commits na área Y ver o patch e aprová-lo, eles podem avisar a quem o enviou para comitá-lo diretamente (mencionando o nome de quem revisou/aprovou na log message, obviamente). Deste modo, o commit virá diretamente da pessoa que fez a mudança, o que é preferível tanto de um ponto de vista gerencial quanto de um ponto de vista de creditação justa.

Por último, e talvez a mais importante, usar o sistema de honra estimula uma atmosfera de confiança e respeito mútuo. Dar permissão de commit à alguém para um subdomínio é uma confirmação feita sobre o preparamento técnico desta pessoa —isto quer dizer: "Nós vemos que você tem proficiência para comitar em uma certa parte do projeto, então vá fundo." No entanto, impor um controle rígido de autorização diz: "Não apenas estamos impondo um limite sobre a sua proficiência, como também estamos um pouco suspeitos das suas intenções." Isto não é algo que você quer dizer se você puder evitar. Trazer alguém para o projeto como um committer é uma oportunidade de iniciá-los em um círculo de confiança. Uma boa maneira de fazer isto é dar mais poder à esta pessoa do que ela deveria ter, e então informá-la que cabe à ela continuar ou não nestes limites.

O projeto Subversion tem operado através sistema de honra há mais de quatro anos, com 33 committers integrais e 43 committers parciais até o tempo de escrita deste livro. A única distinção que o sistema realmente impõe é a entre committers e não-committers; subdivisões adicionais são mantidas apenas por humanos. Ainda assim, nós nunca tivemos problemas com alguém deliberadamente comitar algo fora do seu domínio. Uma ou duas vezes já aconteceram inocentes mal-entendidos sobre o grau de privilégios de commit de alguém, mas tudo sempre foi resolvido de forma rápida e amigável.

Obviamente, em situações onde auto-policiamento é impraticável, você deve contar com controles de autorização rígidos. Mas tais situação são raras. Até quando existem milhões de linhas de código e centenas ou milhares de desenvolvedores, um commit feito a algum módulo deverá ser revisado por quem trabalha neste mesmo módulo, e então pode-se reconhecer caso alguém tenha feito um commit onde não deveria. Se revisões de commit não estão acontecendo frequentemente, então o projeto tem problemas maiores do que lidar com o sistema de autorização.

Em resumo, não perca muito tempo mexendo com o sistema de autorização do controlador de versões, a não ser que você tenha uma razão específica para tal. Isto normalmente não traz benefícios perceptíveis, e existem vantagens em, ao invés disto, confiar em controles humanos.

É claro que nada disto deve ser interpretado de modo que pareça que as restrições, especificamente, não tenham importância nenhuma. Seria muito ruim para um projeto estimular pessoas a comitarem em áreas nas quais não são qualificadas. Além do mais, em muitos projetos, permissão de commit integral (sem restrições) tem um destaque especial: implica em direito de voto em questões de alto nível, que afetam todo o projeto. Este aspecto político de commit é mais discutido em “Who Votes?” em Capítulo 4, Social and Political Infrastructure.