summaryrefslogtreecommitdiffstats
path: root/site/git/index.php
blob: 63c65e6af7937e8a702407ed916781d47c3c1df4 (plain)
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
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
<?php
/*
    Download page
    Copyright (C) 2015  Francis Rowe <info@gluglug.org.uk>

    This program is free software: you can redistribute it and/or modify
    it under the terms of the GNU Affero General Public License as
    published by the Free Software Foundation, either version 3 of the
    License, or (at your option) any later version.

    This program is distributed in the hope that it will be useful,
    but WITHOUT ANY WARRANTY; without even the implied warranty of
    MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
    GNU Affero General Public License for more details.

    You should have received a copy of the GNU Affero General Public License
    along with this program.  If not, see <http://www.gnu.org/licenses/>.
*/
	header('Content-type: text/html; charset=utf-8');
	ob_start();
	include_once "../common/variables.php";
	include_once "../common/functions.php";
?>
<!DOCTYPE html>
<html>
<head>
	<style type="text/css">
		<?php echo miniCss(file_get_contents("../common/css/main.css")); ?>
	</style>
	<title><?php echo gettext("Git repositories"); ?></title>
</head>

<body>

	<div>

		<h1 id="pagetop"><?php echo gettext("Git repositories"); ?></h1>

			<p>
				<?php echo gettext("For a list of current tasks in libreboot, see:"); ?> <a href="../docs/tasks.html">../docs/tasks.html</a>.
				There is also a <a href="http://projects.mtjm.eu/projects/libreboot"><?php echo gettext("bug tracker"); ?></a>
			</p>

			<p>
				<?php echo gettext("Maintenance guides can be found at <a href=\"../docs/maintain/index.html\">../docs/maintain/index.html</a> and <a href=\"../docs/git/index.html\">../docs/git/index.html</a>."); ?>
			</p>

				<ul class="c">
					<li><a href="#guidelines">General guidelines for submitting patches</a></li>
					<li><a href="#download">How to download</a></li>
					<li><a href="#contrib">How to use git, for creating patches</a></li>
					<li><a href="#gitbackup">Backup git repositories</a></li>
				</ul>

			<p><a href="../"><?php echo gettext("Back to home page"); ?></a></p>

	</div>

	<div>

				<h2 id="guidelines">General guidelines for submitting patches  <span class="r"><a href="#guidelines">#guidelines</a></span></h2>
					<p>
						Most people put their name on their work, for recognition, and it's OK if you want to do that; however, the libreboot project does not require this. Some projects
						(such as coreboot) require a legal name, which can be problematic for certain groups of people.
					</p>
					<p>
						Using your legal name is <b>not</b> required when submitting patches to libreboot. For reasons why we have this policy, read <a href='http://geekfeminism.org/2012/09/29/quick-hit-how-git-shows-the-patriarchal-nature-of-the-software-industry/'>this article</a>. You can use an assumed name, or your company name (if you have a company), if you want. Also, read <a href='http://www.kalzumeus.com/2010/06/17/falsehoods-programmers-believe-about-names/'>this article</a>. Unfortunately, git appears to be stuck with these problems, when an author changes their name, and we don't have a concrete answer to it.
						As far as we know, publishing your legal name isn't even required for copyright purposes; in fact, &quot;pen names&quot; are common in literature. You can also
						submit patches without a name, if you want (instructions are detailed on this page).
					</p>
					<p>
						When submitting any kind of documentation, try not to use the terms him/her, she/he, his/her, or anything that is gender biased. <b>Use their, they, them, those people, that person, and so on.</b> <a href="https://gist.githubusercontent.com/0xabad1dea/8870b192fd1758743f66/raw/a230fa3438ce60c538dba31830fa88143245b719/singularthey.md">You are making a huge difference</a>. 
					</p>
					<p>
						<?php echo gettext("Generally speaking, using the same license as the file that you are modifying is much simpler."); ?>
						<?php echo gettext("If you are submitting new files, please make sure that they are under a free license (<a href='https://copyleft.org/'>copyleft</a> preferred)."); ?>
						<?php echo gettext("You can find a list on:"); ?> <a href="https://www.gnu.org/licenses/license-list.html">https://www.gnu.org/licenses/license-list.html</a>. NOTE:
						not putting a copyright notice on a work does not mean it lacks copyright. Copyright is <i>automatic</i> in most countries. Not putting a license
						on a work also does not make that work <i>free</i>; you have to declare a free license, otherwise the default, restrictive copyright laws apply for those
						who wish to do anything with your work. Always put a license on your work!
					</p>
					<p>
						Small technical note: libreboot is working to convert all documentation to <i>texinfo</i>, where
						it is currently written in HTML, directly. Therefore, please submit any new documentation under this format, during the transition period.
					</p>
					<p>
						Information about maintainers to notify, when submitting patches, can be found on the <a href="../contrib/">project maintainers</a> page. Generally speaking,
						libreboot uses a very informal review method for patches. Most patches are merged, unless they obviously have problems. We recommend submitting them to the
						libreboot development mailing list, linked to from the <a href="../">home page</a>. There is also an IRC channel.
					</p>

			<p>
				<a href="#pagetop">Back to top of page</a>
			</p>

	</div>

	<div>

		<h2 id="download"><?php echo gettext("How to download"); ?>  <span class="r"><a href="#download">#download</a></span></h2>
			<p>
				Libreboot development is facilitated by <i><a href="https://git-scm.com/">git</a></i>, a <i>distributed</i> version control system.
				You will need to install git (most GNU/Linux distributions package it in their repositories).
			</p>
			<h3><?php echo gettext("Coreboot distribution. <i>This also contains the documentation</i>:"); ?></h3>
			<p>
				<b>git clone <?php echo $lbFirmwareGitRepoAddress; ?></b><br/>
				<a href="<?php echo $lbFirmwareGitwebAddress; ?>">Browse repository via web</a>
			</p>
			<h3><?php echo gettext("Website. <i>Documentation is in the other repository</i>:"); ?></h3>
			<p>
				<b>git clone <?php echo $lbWebsiteGitRepoAddress; ?></b><br/>
				<a href="<?php echo $lbWebsiteGitwebAddress; ?>">Browse repository via web</a>
			</p>
			<p>
				<a href="#pagetop">Back to top of page</a>
			</p>

	</div>

	<div>
				<h2 id="contrib"><?php echo gettext("How to use git, for creating patches"); ?>  <span class="r"><a href="#contrib">#contrib</a></span></h2>
					<p>
						Libreboot development is facilitated by <i>git</i>, a <i>distributed</i> version control system that is in wide use today. Git provides many practical benefits,
						making collective development of software very easy.
					</p>
					<p>
						<?php echo gettext("The <a href=\"http://git-scm.com/doc\">git documentation</a> describes how to use git. The following notes include simple tips for how to use git, but it is a good idea to get fully acquainted with git."); ?>
					</p>
					<p>
						<?php echo gettext("Make sure that you configured git so that your name and email address appear in the commits that you create:"); ?><br/>
						$ <b>git config --global user.name &quot;Your Name&quot;</b><br/>
						$ <b>git config --global user.email your@emailaddress.com</b><br/>
						<b>NOTE: you don't have to use your legal name. We don't care what name you use. If you want to be anonymous (no name), you could use <i>Libreboot Contributor</i> as your name, and <i>noname@libreboot.org</i> as the email address.</b>
					</p>
					<p>
						<?php echo gettext("The following is also useful:"); ?><br/>
						$ <b>git config --global core.editor nano</b><br/>
						$ <b>git config --global color.status auto</b><br/>
						$ <b>git config --global color.branch auto</b><br/>
						$ <b>git config --global color.interactive auto</b><br/>
						$ <b>git config --global color.diff auto</b>
					</p>
					<p>
						<b>NOTE: the above steps for colour make git use red/green font colours for showing diffs. If you are red/green colour-blind, please ignore the above steps. The default configuration in git is no-colour (all one colour, usually the default that your terminal uses). If you are colour-blind, git can display in other colours; refer
						to the git documentation.</b>
					</p>
					<p>
						<?php echo gettext("Clone the git repository, and make your desired changes."); ?>
						<?php echo gettext("You can make one or several commits (as many as you like)."); ?>
						<?php echo gettext("Generally speaking, you should create separate commits on top of each other, for each kind of change."); ?>
					</p>
					<p>
						<?php echo gettext("Once you have made your change(s), you can use this to check the status:"); ?><br/>
						$ <b>git status</b>
					</p>

					<p>
						<?php echo gettext("The status command will show any untracked files that you have. Add them using <b>git add path/to/file</b>. You should also add any other files that are listed as modified in the git status. If there are deleted files in the git status, you can use <b>git rm path/to/file</b>. As long as you have added all the untracked files, it is generally easier to use:"); ?><br/>
						$ <b>git commit -a</b><br/>
						<?php echo gettext("(instead of <b>git commit</b>)"); ?>
					</p>
					<p>
						<?php echo gettext("If you need to make a change to the current commit, you can do so with:"); ?><br/>
						$ <b>git commit --amend</b><br/>
						<?php echo gettext("or:"); ?><br/>
						$ <b>git commit -a --amend</b>
					</p>

					<p>
						If you wish to use a different author name for the commit command, add <b><i>--author=&quot;Author's Name &lt;author's email address&gt;&quot;</i></b> at the end. This
						could be an assumed name, or it could be because you are submitting a patch on someone else's
						behalf. <b>If you want to be anonymous (no name), you could use <i>Libreboot Contributor</i> as your name, and <i>noname@libreboot.org</i> as the email address.</b>
					</p>
					<p>
						Check once more that everything you want is added. Use the <b>git status</b> command to check for untracking changes/files, and adapt accordingly.
						Once you've committed everything, your changes will appear in a <i>diff</i> format, using this command:
						$ <b>git show</b><br/>
						Use PgUp/PgDown to navigate the diff output. This uses the <i>less</i> utility, so all the features from that (e.g. keyword search) are also available.
					</p>

					<p>
						<?php echo gettext("In your local git tree, you can use this to check your commits:"); ?><br/>
						$ <b>git log</b>
					</p>
					<p>
						<?php echo gettext("Shortened git logs showing the short commit ID and the commit title, plus info about what branch you are on, and where all your remotes/heads are:"); ?><br/>
						$ <b>git config --global --add alias.lol &quot;log --graph --decorate --pretty=oneline --abbrev-commit --all&quot;</b><br/>
						<?php echo gettext("From then on, you can use:"); ?><br/>
						$ <b>git lol</b><br/>
						<?php echo gettext("This is like <b>git log</b>, but it's much better and shows branches, etc."); ?>
					</p>
					<h3><?php echo gettext("Method 1: host a repository"); ?></h3>
						<p>
							<?php echo gettext("Give the checkout details to the libreboot project, along with information on which commits in what branch contain your changes."); ?>
						</p>
					<h3><?php echo gettext("Method 2: git format-patch -N"); ?></h3>
						<p>
							<?php echo gettext("Use this method (replace N with the number of commits that you made) and send the .patch files to the libreboot project, along with details on what branch and revision these were made on top of."); ?>
						</p>
					<p>
						<?php echo gettext("Contact the libreboot project using the details on the home page, sending your patch(es). The mailing list is generally preferable, although IRC can also be just as good for small patches (you would probably put the patch on a paste site)."); ?>
					</p>

			<p>
				<a href="#pagetop">Back to top of page</a>
			</p>
	</div>

	<div>
				<h2 id="gitbackup"><?php echo gettext("Backup repositories"); ?>  <span class="r"><a href="#gitbackup">#gitbackup</a></span></h2>

					<h3><?php echo gettext("Firmware (coreboot distribution)"); ?></h3>
						<p>
	<?php
		for ($server=0; $server<count($lbFirmwareBackupGitRepoAddress); $server++) {
	?>
							$ <b>git clone <?php echo $lbFirmwareBackupGitRepoAddress[$server]; ?></b>
							<?php if ($server!=count($lbFirmwareBackupGitRepoAddress)-1) echo "<br/>"; ?>
	<?php
		}
	?>
						</p>

					<h3><?php echo gettext("Libreboot website"); ?></h3>
						<p>
	<?php
		for ($server=0; $server<count($lbWebsiteBackupGitRepoAddress); $server++) {
	?>
							$ <b>git clone <?php echo $lbWebsiteBackupGitRepoAddress[$server]; ?></b>
							<?php if ($server!=count($lbWebsiteBackupGitRepoAddress)-1) echo "<br/>"; ?>
	<?php
		}
	?>
						</p>

			<p>
				<a href="#pagetop">Back to top of page</a>
			</p>
	</div>

<?php
	include "../common/footer.php";
?>

</body>
</html>
<?php
	$strHtml = ob_get_clean();
	echo miniHtml($strHtml);
?>