...

Note that these are all notes about working with Git in this specific project; Git has such a flexible array of composable tools that each project needs to establish its own conventions, and one project's workflow may not suit another project's requirements.

Files and Directories

Git does not track empty directories. If there's a reason you need the Git repository to contain a directory with no contents (one common case is a src/main/resources or src/test/resources expected by Eclipse) then the closest you can get is a directory with a hidden placeholder file. One common convention for this is to use an empty file called .gitkeep.

...

Release tags should always include a comment of the form Tag version release and  and be signed using the releaser's GPG key using the -s option. For  For this to work, you will need to set your user-level ("global") configuration appropriately:

git config --global user.signingkey 0xkeyId

Then, sign as follows:

git tag -s -m "Tag 1.2.2 release" 1.2.2

...

Although some online documents may suggest the use of git push --tags, you should never use this, as it pushes all tags in your repository.

Branches

The main branch in a Shibboleth project repository is where work on the next feature release occurs. Maintenance work for previously released versions of the software is performed on branches named maint-release, such as maint-3 or maint-3.4.

...

The first line of a comment should be a summary. This  This should be short; limiting it to between 40 between 40 and 50 characters allows it to be properly displayed in things like short logs. If you want to include a JIRA case number, put that at the start of the line separated out by a " - " sequence, e.g.:

ABC-123 - fix typo in log message

If more detail is required in the comment than can be conveyed by the summary, it is followed by a blank line and any and any amount of detailed additional text. The blank line is important to some tools, so don't omit it. The additional text should be line-wrapped at something like 72 columns or thereabouts, as not all contexts in which it is displayed will wrap lines for you and overlong lines will make the comment hard to read.

Tim Pope's note about Git commit messages goes into more detail, and is well worth reading. A later summary of best practices is here.

Referring to the JIRA case using a URL sometimes makes sense if done in the additional text, not in the summary. Referring to other URLs can make sense too, as long as you're referencing something that won't move elsewhere in the lifetime of the codebase. For example, referring to another commit by referring to a web view URL is prone to failure in the longer term.

...

The normal workflow for such a development branch would be:

• Start from the main branch: git checkout main 

• Create local development branch: git checkout -b dev/my-feature 

• Publish development branch: git push -u origin dev/my-feature

• ... perform feature development ...

• ... any series of commits, merges, rebases, squashes, etc. ...

• Prepare to merge development branch: git rebase -i main 

• Move back to parent branch: git checkout main 

• Bring in the feature's final set of commits: git merge --ff-only dev/my-feature 

• Publish: git push 

• Delete remote development branch: git push --delete dev/my-feature

• Delete local development branch: git branch -d dev/my-feature

Permissions

To support (and to some extent enforce) the above workflow, our repository software implements the following rules:

• Committers can perform any operation (fast-forward push, rewind, create, delete, merge) on branches under the dev/ prefix.

• All branches not under dev/ are protected: they only accept fast-forward pushes from committers, can not be created or deleted, and do not accept merge commits.

• Committers can create release tags (named starting with a digits) only. Release tags can not be moved or deleted.

• Administrators can do most of the things committers are restricted from, to allow fixing up certain classes of mistake or taking care of cases we didn't think of.

• No-one can push merge commits to a protected branch.