Editing and Committing

Please follow these simple guidelines to help everybody get the most out of revision control.

• With each commit, include only a single, self-contained type of change (which will often include changes to multiple files). Keep each change minimal to make it easy to follow edits with git log, annotate, diff etc. For example, confine content changes and formatting changes to separate commits.
• Commit, push and pull frequently. This will help avoid merge conflicts that need to be fixed by hand.
• To make changes easy to spot, it is most useful to use hard linebreaks instead of one-line paragraphs. Avoid altering unaffected lines; do not reflow paragraphs if your edits affect only isolated lines. If the formatting becomes ugly, commit separate formatting-only edits.
• Provide a brief but informative message with each commit.
• Keep the repository self-contained, or include easy-to-follow instructions of how to obtain any required extra material. This is particularly an issue with BibTeX files. For IIS-internal documents, the recommended solution is to only cite publications from IISbib using \bibliography{iisbib,otherbib}, which can then simply be accessed via symbolic links to the respective .bib files in iisbib/exports/. For externally-shared documents, the recommended solution is the inclusion of a custom .bib file in the repository together with the paper, using automatic tools to feed it cited references from external BibTeX databases¹⁾.

• No auto-generated files should be added to the repository²⁾. They are unnecessary and may give rise to nasty merge conflicts. Consider adding a Makefile or scripts for auto-generating files where their making is not obvious.
• Use .gitignore files to keep the workspace clean for git status and friends. List all auto-generated files, including backup files, in .gitignore. Likewise for Subversion, use svn propedit svn:ignore directory.
• Do not commit large, binary files such as videos. Git does not handle these well; git pull can take arbitrarily long³⁾. Rather, keep videos on the IIS server; the recommended place for now is iis:/projects/www/public/videos/.
• Do not keep multiple versions of files in the repository. The repository does this automatically for you.