CollinM edited this page Oct 28, 2012 · 7 revisions

The following is a mixture of project structure and best practices. Ultimately, project workflow is up to each team, but consistent development models make working on multiple repositories much easier.


See WhyGit for how we got here.

Repository Types

Project/Implementation: Repositories of project-specific code, e.g. BioQA (code is not relevant to METAL).

Project-Independent Components: Repositories of components that can be re-used in any/many pipelines and are not tied to a specific project, e.g. Algorithms, ResourceWrappers, etc

A simple test: When writing a component, ask the question "Can this code be used another, different pipeline?" Yes: belongs in a project-independent repository No: belongs in a project repository

Repository Structure

Repositories are largely divided into the two abstract types listed above. Each project gets its own repository and groups of components with similar purpose or function get their own repositories. For example, BioQA has a repository of all pipeline-specific code, but calls components from the ResourceWrapper repository (which contains project-independent components).

Each repository has a team associated with it. The admin of this team is responsible for overall code and documentation quality within the repository. This means they are also the branch maintainer and major release manager.

The simplest repository setup is a flat root directory containing folders of Eclipse projects. This is not a strict rule, but it has worked well so far.

Branching Model

Based on [].

Each branch is a feature or bugfix. Branches should be named according to their purpose, and be merged/killed when appropriate. Team leader is also repository maintainer and in charge of keeping the repository branch-space clean, also decides when a branch is ready to be moved to the master/release.

Master Branch

This branch contains only tested, stable, releasable code. Code commits should never occur on this branch, only merges/push commits from other branches. The repository admin is responsible for the contents of this branch and is the gatekeeper for any code pushed here (generic criteria: adds features, fixes bugs, is documented, etc.) Commits on this branch will correspond to maven releases; this is how other projects will interact with your code. Commits that correspond to a maven release should be tagged with the version number

Develop Branch

This is the main development branch. It represents the stable(ish) state of the art for a given repository. The repository admin is responsible for the contents of this branch (as it is the branch most often pushed to the master branch) and is the gatekeeper for any code pushed here (see generic criteria above). Like the master branch, this branch should only have merge commits, very few to zero code commits.

Active Development/Feature Branches

These are branches from the development branch where active development is taking place (coding, testing, documentation, etc.). Ideally, each repository should have some branch naming convention that makes it clear who owns the branch and what the purpose is (user1-ConceptWeightingFeature). When finished, feature branches are merged back into the development branch (at the admin's discretion), which is eventually merged into the master branch for release.

Commit Messages

Commit messages should at the very least describe the change(s) that was done, and should preferably include the why and how if the change is not trivial (most changes aren't). If the change specifically resolved a ticket, please mention the ticket (number, link, whatever). The ticket should not be the only source of information about the change. The commit message is the single source of truth (to borrow some parlance from information systems). The commit message should document the change (obviously, the documentation should do this too, but that's neither here nor there).

Git Resources/Quick Links

GitHub Tickets

Tickets (in any repository) are for action items. Typically, bug fixes and new features. See here for adding tickets to a repository that you don't work on. All ticket closures should be associated with a commit, if a change is done, and a short description of the fix, if necessary. This helps to leave an audit trail of what's, where's, and why's for code changes.