Git-Server-Side-Checks

VXL Git Server-Side Checks

To ensure that the VXL Git history remains in a clear and organized state we impose a few constraints that are enforced via server-side scripts on the SourceForge server when developers push to the official repository.

Author and Committer

One must always configure contact information (real name and email address) locally before committing changes to VXL. Our development setup instructions and scripts cover this step. A server-side check will reject commits whose author or committer do not look like a "Real Name" and email address with a valid domain name.

Commit Message

Git itself does not enforce any particular layout for commit messages. However, many Git features and third-party tools work best with commit logs when commit messages are formatted as

A brief one-line summary like an email subject line

Optionally followed by a blank line and then free-form text
like an email message body.

A server-side check will reject commit messages:

• that do not follow the above convention
• whose first line is not within a reasonable length range
• whose total size is larger than a reasonable maximum

Newline Style

Git has several configuration options affecting newline conversion for files checked out in the work tree. These work best when the actual file content stored literally in the repository uses LF-only newlines. Furthermore, the newline conversion logic in some versions of Git can become confused when the repository stores a file with literal CRLF newlines. A server-side check will reject pushes that add CRLF newlines to text files.

This check can be relaxed for specific file types marked in the project .gitattributes to have no newline conversion (-crlf or -text), but a project administrator will have to update the check on the server accordingly.

File Size Limit

There is rarely a good reason to store a large file directly in a version-controlled source tree because large files are typically generated by a tool rather than written by hand as an original source of content. If a large file is ever added to the official repository then everyone must pay the cost to store and transmit it as part of the project history even if it is later removed from the current version. A server-side check will reject pushes that add files over 1 MiB unless special arrangements are first made through discussion on the mailing list.

Fixed Set of Branches

The official repository publishes a fixed set of "integration" branches into which all work must be merged. Developers may not create new branches or delete existing branches. The distributed nature of Git allows developers to build their own branches locally during development, to publish them in non-official repositories for sharing and review, and to merge them into an integration branch such as master for publication in the official repository.

Fast-Forward Updates

The official repository branches may be updated only by pushing new commits that contain the existing commits in their history. Developers may not re-write already-published commits or erase them from the repository. Therefore one must rebase or merge local commits with new upstream changes before pushing them. This is Git's equivalent to "svn commit" asking one to run "svn update" first.

First-Parent Sequence

Each official repository branch organizes its history as a linear sequence of events each adding new work on top of what existed previously. We call this a "first-parent sequence" because it may be viewed using the command "git log --first-parent $branch". Each event in the sequence is either a normal commit making a change directly or a merge commit bringing in a whole branch of other commits.

A server-side update check enforces this organization by requiring that each new branch head contains the old branch head in its first-parent sequence. This prevents developers publishing a backward merge in the first-parent sequence (merging the upstream into one's local branch instead of the other way around). Developers must always rebase their work on an upstream branch or merge their local branch into it.

Root Commit Not Allowed

All development should start from an existing commit in history so all commits should have at least one parent commit. A server-side update check will reject pushes containing commits with no parents. This prevents developers from accidentally merging in history from another project.

User May Not Update Branch

Push access to some branches may be restricted to specific users. Ask on the mailing list for details of a specific case.

Updates Temporarily Not Allowed

During maintenance of the official repository by VXL project administrators we may disable all updates with a message like "updates temporarily not allowed".