Table of Contents
The majority of Adélie Linux projects are stored in a distributed version control system called Git. In this chapter, we will see an overview of how Git works, find out where its documentation lives, and learn about Adélie-specific workflows in Git.
In this section, you will learn:
What Git and distributed version control systems provide;
How to configure Git for work on Adélie Linux projects; and
Where to find documentation about Git.
A version control system is a system that keeps track of a collection of related files, called a repository, and how they change over time. If you are familiar with Mac OS X™'s Time Machine functionality, a version control system is similar to this; it keeps a record of each file, when it was changed, and who changed it. The primary difference is that a version control system only saves records of files when you explicitly tell it to do so. This saving of a record is called a commit, and the list of all commits is called a commit log.
A distributed version control system allows many people to have their own copies of the repository containing the full commit log. When a person wants to provide their commits to others, they push their commits to a central server. Typically, people work on their own branch, or private tree of files. When a person pushes their changed branch to the central server, it allows them to merge other branches.
Git is a distributed version control system that runs on many different kinds of computers, and is very popular in open source development. The Adélie Linux distribution uses Git to track everything from the package repositories, to the documentation set, to libraries and other software written for Adélie Linux.
Git allows us to maintain a record of who has contributed to the project, the date they contributed, and what changes they contributed. It is therefore very important that you configure Git on your system to have your name and email address, so that the commit log attributes you correctly.
If you have not already done so, you must first provide your name and email address to Git. You may do this by running the following two commands:
$ git config --global user.name "Your Name"
$ git config --global user.email "email@address.tld"
If you have a PGP key (used for signing electronic messages), and it is publicly known and cross-signed, you should additionally provide this to Git. This will allow more provability that you are the one who created a commit. You may do this by running the following two commands:
$ git config --global user.signingkey YourPublicKeyFingerprint
$ git config --global commit.gpgsign true
There are many helpful resources available for you to learn more about Git. You may install the git-doc package on your Adélie computer for easy access to the built-in manuals. Additionally, if you have access to the World Wide Web, you may read the freely-licensed Pro Git book. There are also a number of mailing lists for starting out and working with Git.
In this section, you will learn:
How the Adélie Linux distribution uses Git branches and commits;
How to write a good, informative commit message; and
A guideline on how frequently to make commits and merge requests.
A branch is a self-contained copy of a project's files. Using branches allows your changes to be reviewed quickly and, if approved, merged in to the Adélie Linux source quickly. A branch should be a single "unit of work". That is, a branch should have a single goal in mind. Sometimes a branch can contain many commits; for instance, your goal may be "update the Gnome Office packages". In that case, you would have at least one commit for each Gnome Office package. However, sometimes a branch only needs one commit. This can be useful for simple bug fixes, or bumping a single package's version.
Branches should have a name that reflects their goal. A branch name such as bugfix or version is unclear and doesn't communicate the goal of the branch. A branch name such as gnumeric-1.12.35-update or fix-boot-on-g3 is clear and concisely states the branch goal.
If you are not currently an Adélie Linux developer, you will create the branches in your fork, which is a private copy of the repository that is owned by you. If you are an Adélie Linux developer, you can create the branch in your own private fork or the main repository. For more information about creating forks, see the GitLab documentation.
A commit message should have the following structure:
area: summary of change
Multi-line details of change, if necessary.
Signed-off-by: Your Name <email@address.tld>
Acked-by: Developer Name <email@adelielinux.org>
(1) |
The area changed by the commit. For source code, this is typically the module name (such as |
(2) |
A brief summary of the commit. The summary line should be less than 60 characters, and be a concise summary of the change made. |
(3) |
A detailed summary of the commit. You may expand on the rationale for the commit, or provide more information than you could in the summary line. |
(4) |
If you are not yet an Adélie Linux developer, use the |
(5) |
If you communicated with an Adélie Linux developer about this change before sending the commit, add the |
There are a few different standards for how often you should commit your work, depending on the repository to which you are contributing.
Some repositories contain guidelines in their Contribution Guide, found in the CONTRIBUTING.rst file in the root of the repository.
As a general guideline, when you are working on a source code repository, each commit should be one "logical change".
This could be adding a new function to an API, or changing an algorithm and ensuring all other files have the updated algorithm.
Similarly, when you are working on a package repository, you should use one commit per package that you change.
For instance, if you "bump" or update the version of three packages, you would use one commit for each of the three packages, for a total of three commits.
This allows an Adélie Linux developer to review each package's change separately.
There are some reasons you may want a single commit to hold changes to multiple packages.
For example, if you are updating the license fields of many packages, you may want a single commit with a message similar to main/libx*: Update licenses on X11 libraries.