1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
|
<?xml version="1.0" encoding="utf-8"?>
<chapter label="3" id="git">
<title>Git Basics</title>
<para>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.</para>
<section>
<title>Getting Started with Git</title>
<para>In this section, you will learn:</para>
<itemizedlist>
<listitem><para>What Git and distributed version control systems provide;</para></listitem>
<listitem><para>How to configure Git for work on Adélie Linux projects; and</para></listitem>
<listitem><para>Where to find documentation about Git.</para></listitem>
</itemizedlist>
<section>
<title>What is Git?</title>
<para>A <firstterm>version control system</firstterm> is a system that keeps track of a collection of related files, called a <firstterm>repository</firstterm>, and how they change over time.
If you are familiar with <productname>Mac OS X</productname>'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 <firstterm>commit</firstterm>, and the list of all commits is called a <firstterm>commit log</firstterm>.</para>
<para>A <firstterm>distributed version control system</firstterm> 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 <firstterm>push</firstterm> their commits to a central server.
Typically, people work on their own <firstterm>branch</firstterm>, or private tree of files. When a person pushes their changed branch to the central server, it allows them to <firstterm>merge</firstterm> other branches.</para>
<para><firstterm>Git</firstterm> 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.</para>
<para>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.</para>
</section>
<section>
<title>Configuring Git</title>
<para>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:</para>
<para><prompt>$</prompt> <command>git <parameter>config</parameter> <parameter>--global</parameter> <parameter>user.name</parameter> <userinput>"Your Name"</userinput></command></para>
<para><prompt>$</prompt> <command>git <parameter>config</parameter> <parameter>--global</parameter> <parameter>user.email</parameter> <userinput>"email@address.tld"</userinput></command></para>
<para>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:</para>
<para><prompt>$</prompt> <command>git <parameter>config</parameter> <parameter>--global</parameter> <parameter>user.signingkey</parameter> <userinput>YourPublicKeyFingerprint</userinput></command></para>
<para><prompt>$</prompt> <command>git <parameter>config</parameter> <parameter>--global</parameter> <parameter>commit.gpgsign</parameter> <parameter>true</parameter></command></para>
</section>
<section>
<title>Learning More about Git</title>
<para>There are many helpful resources available for you to learn more about Git.
You may install the <package>git-doc</package> 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 <ulink url="https://git-scm.com/book/en/v2"><citetitle pubwork="book">Pro Git</citetitle> book</ulink>.
There are also a number of mailing lists for starting out and working with Git.</para>
</section>
</section>
<section>
<title>Using Git with Adélie</title>
<para>In this section, you will learn:</para>
<itemizedlist>
<listitem><para>How the Adélie Linux distribution uses Git branches and commits;</para></listitem>
<listitem><para>How to write a good, informative commit message; and</para></listitem>
<listitem><para>A guideline on how frequently to make commits and merge requests.</para></listitem>
</itemizedlist>
<section>
<title>Using Branches</title>
<para>A <firstterm>branch</firstterm> 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.</para>
<para>Branches should have a name that reflects their goal. A branch name such as <literal>bugfix</literal> or <literal>version</literal> is unclear and doesn't communicate the goal of the branch. A branch name such as <literal>gnumeric-1.12.35-update</literal> or <literal>fix-boot-on-g3</literal> is clear and concisely states the branch goal.</para>
<para>If you are not currently an Adélie Linux developer, you will create the branches in your <firstterm>fork</firstterm>, 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.</para>
</section>
<section>
<title>Commits</title>
<para>A commit message should have the following structure:</para>
<screenco>
<areaspec>
<area id="commit_area" coords="1 1"/>
<area id="commit_summary" coords="1 7"/>
<area id="commit_detail" coords="3"/>
<area id="commit_signedoff" coords="5"/>
<area id="commit_acked" coords="6"/>
</areaspec>
<screen>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>
</screen>
<calloutlist>
<callout arearefs="commit_area">
<para>The area changed by the commit. For source code, this is typically the module name (such as <filename>string</filename> or <filename>gnulib</filename>). For packages, this is the full name of the package, such as <filename>user/dejagnu</filename>.</para>
</callout>
<callout arearefs="commit_summary">
<para>A brief summary of the commit. The summary line should be less than 60 characters, and be a concise summary of the change made.</para>
</callout>
<callout arearefs="commit_detail">
<para>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.</para>
</callout>
<callout arearefs="commit_signedoff">
<para>If you are not yet an Adélie Linux developer, use the <parameter>--signoff</parameter> parameter to <command>git</command> to reflect that you agree to the contribution guidelines of the repository.</para>
</callout>
<callout arearefs="commit_acked">
<para>If you communicated with an Adélie Linux developer about this change before sending the commit, add the <literal>Acked-by</literal> line to reflect such. This will make it easier for further review to continue.</para>
</callout>
</calloutlist>
</screenco>
<para>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 <filename>CONTRIBUTING.rst</filename> 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.</para>
<para>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 <literal>main/libx*: Update licenses on X11 libraries</literal>.</para>
</section>
</section>
</chapter>
|
