GitMajorWorkflow

Introduction

This is intended for development which will take more than a day, perhaps up to months, and may involve multiple contributors and validators, or should be documented in the git repository for some time. They may also mark breaking changes, need to be coordinated with product changes, other branches, or tags. Currently we plan to leave these branches visible in the repository until they are no longer of interest, at which time they may be archived so as to not clutter the repo forever.

If you are new to git, please read the git intro and the minor revision workflow, which is very useful for concepts.

Overview

The logical steps are as follows.

1. checkout or create a work branch
2. make revisions and commit them
3. as needed, push this branch to the repo
4. as needed, merge the head into your working branch
5. when the changes are final, merge your branch into the head.

This workflow may span weeks, so steps 3 and 4 may need to be done several times. It is fine to save your work this way. It may be needed to tag the branch at various times, to pause for testing, for example, or to pass a given state to another worker.

Cheat Sheet

> git checkout -b <meaningfulBranchName>

where <meaningfulBranchName> is a name that encapsulates the set of software changes you'll be making, such as GeomForMARS2018a, etc.

Do your work. Edit/create/move files, etc. git add files to track them, commit them when ready.

Assuming this is a "long-term" development project, you'll want to occasionally bring in the most up-to-date master and make sure there are no conflicts. I'd like to see git experts weigh in on the best way to do this. Merge, rebase, other?

Also, I think we need to nail down our request to pull mechanism and get that into the cheat sheet.

Naming branches and tags

We suggest branch names made up of 3 parts

1. the starting point. Thsi is relevant if the starting point is a tagged release or other significant commit. If the start of the branch is the current head, and has no significance, it can be left off.
2. the nemonic name. The string which tells any casual viewer the purpose of the work
3. the word "branch"

A branch name might look like:

v5_7_9-cosmic_target5-branch       # branch

If you need to tag the branch to label a particular commit, perhaps for testing, replace the "branch" with the version of the tag. The version will start at zero for each new branch and advance

v5_7_9-cosmic_target5-v0   # tag