Git Collaboration: Glossary

First key point. Brief Answer to questions. (FIXME)

Several services exist that offer hosting of Git repositories.

Hosting of public and/or Open-Source projects is mostly free of charge.

Hosting of non-public repositories often requires a paid-for plan or has certain restrictions.

Several self-hosted solutions exist.

Issues are used to plan further development.

Developers and users will communicate so that developers can reproduce bugs.

Enhancements and feature requests are discussed, working out the expected use-cases as well as parts of the implementation.

Issues of bugs and enhancements that cannot be immediately be resolved stay open so that they are not forgotten.

By forking a repository you create a copy under your own account.

You can use this ‘fork’ to develop you own feature or fix a bug that’s bugging you.

This can be the base for contributing these changes back to the original project.

Sometimes however it is used to initiate an independent spin-off that will diverge over time.

Pull requests are used to merge commits between repositories that share a common ancestor.

Like issues contributors and maintainers can communicate via comments.

Commits that are pushed to the branch that is to be merged become part of the PR.

Once a maintainer is satisfied with the contribution, they merge the pull request.

Pull requests are closed by either merging or rejecting them.

Code review increases code quality.

The reviewer checks whether the contribution conforms to the set standards.

When has »I promise I’ll write the documentation/tests later!« ever worked?

A second pair of eyes might find a more elegant solution.

The reviewer might learn something new when reading someone else’s code.

Running automated tests often helps tracking down bugs early.

With CI, tests are being executed anytime changes are pushed to the repository.

CD is used to automate the deployment of new releases.

Software releases add version numbers to specific states within the development cycle.

This is done by attaching Tags – immutable labels – to a certain commit.

Using ‘Semantic Versioning’ helps to communicate to a user what they can expect when upgrading.

Never change a release retroactively or re-release the same version with different content.

With Zenodo you can get a DOI for any release hosted on GitHub, making that version citable.

git branch bname creates a new branch bname from the currently checked-out commit.

git checkout bname switches the workspace to the branch bname.

git checkout -b bname combines the commands git branch bname and git checkout bname and creates the new branch bname and switches to it with the same command.

git merge bname merges the branch bname into the currently active branch. It’s always the currently active (checked-out) branch that is being changed.

git branch -d bname deletes a branch that has been merged.

To delete un-merged branches, we have to force git to delete them by using -D instead of -d. This is to prevent accidentally deleting those branches and loosing data.

Wikis are an easy way to share simple documentation.

Developers can edit the documentation within the browser.

Permissions can be set to allow any user to edit pages.

This allows crowd-sourcing efforts.

As it is stored in a Git repository, changes can always be reverted.

Markdown is a lightweight and rather intuitive markup-language that is widely used.

GitHub, GitLab and Bitbucket offer a way hosting a website on their platform.

The pages are stored in a Git repository.

The pages are static in a sense that there are no server-side scripts or databases.

GitHub and GitLab offer building pages from e.g. Markdown files with ‘Jekyll’

In those cases Jekyll is executed whenever commits are pushed to the server.

The process works like a CI/CD pipeline.