Kontrolę wersji stosuj nie tylko dla kodu źródłowego projeku, ale także strony internetowej, dokumentacji, FAQ, dokumentów projektowych i wszystkiego innego, co ludzie mogliby edytować. Przechowuj je zaraz obok kodu, w tym samym repozytorium. Każdą informację, którą warto zapisać, warto też wersjonować—a więc każdą informację, która może ulec zmienie. Rzeczy które nie ulegają zmianie powinny być archiwizowane, nie wersjonowane. Na przykład email po wysłaniu nie może już zmienić treści, a więc kontrola wersji w tym przypadku nie miałaby sensu (do czasu, gdy nie stanie się częścią jakiegoś większego, ewolującego dokumentu).

Wersjonowanie wszystkiego razem, w jednym miejscu, jest tak ważne, gdyż wtedy ludzi muszą nauczyć się tylko jednego mechanizmu nadsyłania zmian. Często uczestnik projektu zaczyna od edycji strony internetowej czy dokumentacji, a następnie stopniowo przechodzi do trudniejszych zadań. Gdy projekt korzysta z tego samego systemu dla wszystkich zmian, ludzi muszą nauczyć się korzystać z niego jedynie raz. Wersjonowanie wszystkiego razem oznacza też, że commit nowego kodu może zawierać też aktualizację dokumentacji, utworzenie gałęzi kodu tworzy także gałąź dokumentacji, i tak dalej.

W przechowuj w repozytorium plików generowanych. Nie są one edytowalnymi danymi, gdyż są generowane automatycznie na podstawie innych plików. Na przykład niektóre systemy budowania tworzą plik configure w oparciu o szablon configure.in. Aby dokonać zmian w pliku configure należy wyedytować configure.in i wygenerować plik wynikowy, a więc jedynie szablon jest "plikiem edytowalnym". Wersjonuj jedynie szablony—jeśli będziesz wersjonować także pliki wynikowe, ludzi będą zapominać o tym, aby je ponownie wygenerować po dokonaniu zmian w szablonie, a wynikające z tego niespójności będą prowadzić do sporego zamieszania.^[18]

Od zasady mówiącej, że wszystkie edytowalne dane powinny być przechowywane w systemie kontroli wersji, jest niestety jeden wyjątek: system śledzenia błędów. Bazy błędów zawierają wiele edytowalnych danych, ale z powodów technicznych nie przechowują ich w głównym systemie kontroli wersji. Niektóre z nich mają własne prymitywne możliwości wersjonowania, są one jednak zupełnie niezależne od głównego repozytorium projektu.

Repozytorium projektu powinno dać się przeglądać przy użyciu przeglądarki internetowej. Nie chodzi tu tylko o możliwość dostępu do najnowszych wersji plików, ale także cofanie się w czasie i podgląd starych wersji, porównywanie różnic pomiędzy wersjami, czytania komentarzy do zmian, i tak dalej.

Możliwość przeglądania jest istotna, ponieważ daje możliwość łatwego dostępu do danych projektu. Gdyby repozytorium nie było dostępne za pomocą przeglądarki, wtedy każdy kto chciałby sprawdzić zawartość jakiegoś pliku (na przykład aby sprawdzić, czy pewna poprawka została dołączona do kodu) musiałby najpierw zainstalować u siebie klienta systemu kontroli wersji, co mogłoby zmienić kilkuminutowe zapytanie w pół godzinne zadanie.

Możliwość przeglądania zakłada też istnienie standardowych adresów do przeglądania wybranych wersji plików, włączając w to tę najnowszą. To może być bardzo przydatne w dyskusjach technicznych lub w odsyłaczach do dokumentacji. Na przykład zamiast mówić "Aby znaleźć porady dotyczące debugowania serwera sprawdź plik www/hacking.html w swojej kopii roboczej" można powiedzieć "Aby znaleźć porady dotyczące debugowania serwera sprawdź http://subversion.apache.org/docs/community-guide/", podając adres wskazujący na najbardziej aktualną wersję pliku hacking.html. Adres URL jest lepszy, ponieważ jest jednoznaczny i niezależny od tego, na ile aktualną kopię roboczą posiada adresat.

Niektóre systemy kontroli wersji posiadają wbudowane mechanizmy do przeglądania repozytorium, inne polegają na zewnętrznych narzędziach. Takimi narzędziami są ViewCVS (http://viewcvs.sourceforge.net/), CVSWeb (http://www.freebsd.org/projects/cvsweb.html), i WebSVN (http://websvn.tigris.org/). Pierwszy z nich współpracuje zarówno z CVS jak i Subversion, drugi jedynie z CVS, a trzeci tylko i wyłącznie z Subversion.

Każdy commit do repozytorim powinien powodować wysłanie emaila zawierającego informacje o autorze zmian, czasie ich wykonania, zmodyfikowanych plikach i różnicach w stosunku do wersji pierwotnej. Ten email powinien zostać wysłany na specjalną listę dyskusyjną, odrębną od tej, na której dyskutują ludzie. Programiści (i inne zainteresowane osoby) powinni być zachęcani do subskrybowania tej listy, gdyż jest to najefektywniejszy sposób na to, aby śledzić zmiany w projekcie na poziomie kodu. Oprócz oczywistych zalet takiego przeglądu kodu (patrz „Practice Conspicuous Code Review”), takie powiadomienia wzmacniają społeczność, gdyż tworzą wspólne forum na którym ludzie mogą reagować na zdarzenia (commity) widoczne dla wszystkich innych.

Szczegóły konfiguracji powiadomień są zależne od konkretnego systemu kontroli wersji, ale na ogół istnieje gotowy skrypt, który można w tym celu wykorzystać. Jeśli masz problemy z jego odnalezieniem, spróbuj poszukać w dokumentacji pod hasłem hooks, a w szczególności post-commit hook (w terminologii CVS loginfo hook). Nie ma przyjętego polskiego odpowiednika, więc na potrzeby tego rozdziału użyjemy bezpośredniego tłumaczenia "hak". Haki post-commit pozwalają na automatyczne wykonywanie pewnych zadań w odpowiedzi na commi. Hak zostaje wykonany dla każdego commita, otrzymując wszystkie konieczne informacje o nim—których może użyć na przykład do wysłania emaila.

Czasem warto zmodyfikować domyślne zachowanie gotowego skryptu wysyłającego powiadomienia:

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 Rozdział 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 has an important corollary: never commit the same change twice. That is, a given change should enter the version control system exactly once. The revision (or set of revisions) in which the change entered is its unique identifier from then on. If it needs to be applied to branches other than the one on which it entered, then it should be merged from its original entry point to those other destinations—as opposed to committing a textually identical change, which would have the same effect in the code, but would make accurate bookkeeping and release management impossible.

The practical effects of this advice differ from one version control system to another. In some systems, merges are special events, fundamentally distinct from commits, and carry their own metadata with them. In others, the results of merges are committed the same way other changes are committed, so the primary means of distinguishing a "merge commit" from a "new change commit" is in the log message. In a merge's log message, don't repeat the log message of the original change. Instead, just indicate that this is a merge, and give the identifying revision of the original change, with at most a one-sentence summary of its effect. If someone wants to see the full log message, she should consult the original revision.

The reason it's important to avoid repeating the log message is that log messages are sometimes edited after they've been committed. If a change's log message were repeated at each merge destination, then even if someone edited the original message, she'd still leave all the repeats uncorrected—which would only cause confusion down the road.

The same principle applies to reverting a change. If a change is withdrawn from the code, then the log message for the reversion should merely state that some specific revision(s) is being reverted, not describe the actual code change that results from the reversion, since the semantics of the change can be derived by reading the original log message and change. Of course, the reversion's log message should also state the reason why the change is being reverted, but it should not duplicate anything from the original change's log message. If possible, go back and edit the original change's log message to point out that it was reverted.

All of the above implies that you should use a consistent syntax for referring to revisions. This is helpful not only in log messages, but in emails, the bug tracker, and elsewhere. If you're using CVS, I suggest "path/to/file/in/project/tree:REV", where REV is a CVS revision number such as "1.76". If you're using Subversion, the standard syntax for revision 1729 is "r1729" (file paths are not needed because Subversion uses global revision numbers). In other systems, there is usually a standard syntax for expressing the changeset name. Whatever the appropriate syntax is for your system, encourage people to use it when referring to changes. Consistent expression of change names makes project bookkeeping much easier (as we will see in Rozdział 6, Communications and Rozdział 7, Packaging, Releasing, and Daily Development), and since a lot of the bookkeeping will be done by volunteers, it needs to be as easy as possible.

See also „Releases and Daily Development” in Rozdział 7, Packaging, Releasing, and Daily Development.

Most version control systems offer a feature whereby certain people can be allowed or disallowed from committing in specific sub-areas of the repository. Following the principle that when handed a hammer, people start looking around for nails, many projects use this feature with abandon, carefully granting people access to just those areas where they have been approved to commit, and making sure they can't commit anywhere else. (See „Prawo zapisu” in Rozdział 8, Zarządzanie ochotnikami for how projects decide who can commit where.)

There is probably little harm done by exercising such tight control, but a more relaxed policy is fine too. Some projects simply use an honor system: when a person is granted commit access, even for a sub-area of the repository, what they actually receive is a password that allows them to commit anywhere in the project. They're just asked to keep their commits in their area. Remember that there is no real risk here: in an active project, all commits are reviewed anyway. If someone commits where they're not supposed to, others will notice it and say something. If a change needs to be undone, that's simple enough—everything's under version control anyway, so just revert.

There are several advantages to the relaxed approach. First, as developers expand into other areas (which they usually will if they stay with the project), there is no administrative overhead to granting them wider privileges. Once the decision is made, the person can just start committing in the new area right away.

Second, expansion can be done in a more fine-grained manner. Generally, a committer in area X who wants to expand to area Y will start posting patches against Y and asking for review. If someone who already has commit access to area Y sees such a patch and approves of it, they can just tell the submitter to commit the change directly (mentioning the reviewer/approver's name in the log message, of course). That way, the commit will come from the person who actually wrote the change, which is preferable from both an information management standpoint and from a crediting standpoint.

Last, and perhaps most important, using the honor system encourages an atmosphere of trust and mutual respect. Giving someone commit access to a subdomain is a statement about their technical preparedness—it says: "We see you have expertise to make commits in a certain domain, so go for it." But imposing strict authorization controls says: "Not only are we asserting a limit on your expertise, we're also a bit suspicious about your intentions." That's not the sort of statement you want to make if you can avoid it. Bringing someone into the project as a committer is an opportunity to initiate them into a circle of mutual trust. A good way to do that is to give them more power than they're supposed to use, then inform them that it's up to them to stay within the stated limits.

The Subversion project has operated on the honor system way for more than four years, with 33 full and 43 partial committers as of this writing. The only distinction the system actually enforces is between committers and non-committers; further subdivisions are maintained solely by humans. Yet we've never had a problem with someone deliberately committing outside their domain. Once or twice there's been an innocent misunderstanding about the extent of someone's commit privileges, but it's always been resolved quickly and amiably.

Obviously, in situations where self-policing is impractical, you must rely on hard authorization controls. But such situations are rare. Even when there are millions of lines of code and hundreds or thousands of developers, a commit to any given code module should still be reviewed by those who work on that module, and they can recognize if someone committed there who wasn't supposed to. If regular commit review isn't happening, then the project has bigger problems to deal with than the authorization system anyway.

In summary, don't spend too much time fiddling with the version control authorization system, unless you have a specific reason to. It usually won't bring much tangible benefit, and there are advantages to relying on human controls instead.

None of this should be taken to mean that the restrictions themselves are unimportant, of course. It would be bad for a project to encourage people to commit in areas where they're not qualified. Furthermore, in many projects, full (unrestricted) commit access has a special status: it implies voting rights on project-wide questions. This political aspect of commit access is discussed more in „Who Votes?” in Rozdział 4, Social and Political Infrastructure.