git.mdwn 8.6 KB
Newer Older
1 2 3 4
[[!meta title="Git repositories"]]

<div id="intro">

Tails developers's avatar
Tails developers committed
5
<p>Tails and its website are developed in numerous Git repositories.</p>
6 7 8 9 10

<p><span class="application">Git</span> is a distributed version control
system. It allows several people to work on the same source code and
handle changes in a distributed and efficient way.</p>

11
</div>
12

13
[[!toc levels=3]]
14

15
<a id="learn_Git"></a>
16

17 18 19 20 21 22
Learn Git
=========

<p>To learn more about <span class="application">Git</span>, refer to
its <a href="http://git-scm.com/">homepage</a>, and <a
href="http://git-scm.com/documentation">official documentation</a>.</p>
Tails developers's avatar
Tails developers committed
23

24 25
Here are a couple of links to get started with Git:

26
- An [interactive introduction](https://try.github.io/) to Git
27
- [Git basics](https://www.atlassian.com/git/tutorial/git-basics), by Atlassian
28
- [Git immersion](http://gitimmersion.com/), a step-by-step introduction
29 30
- Pro Git: [online](http://git-scm.com/book),
  [PDF](https://github.s3.amazonaws.com/media/progit.en.pdf), a book on Git from
31 32
  basic to advanced usage. This book is available in several languages. Among others:
  [German](http://git-scm.com/book/de), [French](http://git-scm.com/book/fr), [Português](http://git-scm.com/book/pt-br) (Brasil)
33 34 35 36 37
- [OpenHatch Missions: Using Git](https://openhatch.org/missions/git), concrete
  exercises to train yourself in using Git.
- [Git For Ages 4 And
  Up](http://mirror.linux.org.au/linux.conf.au/2013/mp4/Git_For_Ages_4_And_Up.mp4),
  a video on learning Git.
38

39 40
<a id="general-information"></a>

41 42 43
General information
===================

44 45
Git hosting setup at immerda
----------------------------
46

Tails developers's avatar
Tails developers committed
47
Documentation for our Git hosting setup at immerda:
48 49

* [main documentation](https://wiki.immerda.ch/index.php/GitRepositoriesImmerda)
Tails developers's avatar
Tails developers committed
50
* [SSL and SSH fingerprints](https://www.immerda.ch/infos/certs.html)
51

Tails developers's avatar
Tails developers committed
52 53 54 55 56
Merge policy
------------

See our [[contribute/merge_policy]].

57 58 59
Caution!
--------

60
If you intend to prepare Tails releases, you'll need to make
61 62
the development team signing key the default one for Git tags:

63
	git config user.signingkey A490D0F4D311A4153E2BB7CADBB802B258ACD84F
64 65 66 67

Creating a new repository
-------------------------

68
Create a new repository at immerda.
69

70 71 72
Repositories
============

Tails developers's avatar
Tails developers committed
73 74
<a id="main-repo"></a>

75
Main repository
76
---------------
77

sajolida's avatar
sajolida committed
78
This repository contains the Tails source code and the source of the website.
79

80
Anyone can check it out like this:
amnesia's avatar
amnesia committed
81

82
	git clone https://git-tails.immerda.ch/tails
83 84 85

Developers with write access to the repositories should instead:

86
	git clone boum_org_amnesia@webmasters.boum.org:wiki.git
87

88 89 90 91
And then, in any case, in your new Git clone's directory:

	git submodule update --init

92 93 94
For more information about our usage of Git submodules, see
[[the dedicated section|git#submodules]].

Tails developers's avatar
Tails developers committed
95 96
We have a [web interface](https://git-tails.immerda.ch/tails/)
available for the main repository.
97

98 99 100 101 102 103 104
### Configuration

Developers with write access to the repositories should:

	git config --global url.tails@git.tails.boum.org:.insteadOf \
	   https://git-tails.immerda.ch/

Debian Live user's avatar
Debian Live user committed
105 106
<a id="branches"></a>

107
### Branches
108

109
Tails development uses several branches modeled a bit like the
110 111
Debian development process. Here they are.

Debian Live user's avatar
Debian Live user committed
112 113
<a id="master_branch"></a>

114
#### master
115

116
The `master` branch is mostly used to build the website. It is
Debian Live user's avatar
Debian Live user committed
117
merged into `devel` and `stable` from time to time.
sajolida's avatar
sajolida committed
118
We merge into `master`:
Debian Live user's avatar
Debian Live user committed
119

Debian Live user's avatar
Debian Live user committed
120 121
- [[Documentation improvements|contribute/how/documentation]] that
  affect current Tails (e.g. not the next Tails release).
sajolida's avatar
sajolida committed
122
- Other changes to the website ([[news]], [[security advisories|security/]], layout, and so on).
123
- [[Translations|contribute/how/translate#website]] of the website.
Debian Live user's avatar
Debian Live user committed
124
- When [[releasing a new Tails|contribute/release_process/]], the branch
sajolida's avatar
sajolida committed
125
  the release was built from (`stable` or `testing`).
126

127
#### stable
128 129 130 131 132 133 134 135

The `stable` branch is intended to contain:

- the state of the code tagged for the last stable release
- fixes for security or important bugs.

Its purpose is to prepare minor releases.

136
#### testing
137 138 139

The `testing` branch is used to prepare an imminent release: at some
point of the development process, the `devel` branch code is merged
Bessemer's avatar
Bessemer committed
140
into `testing`, frozen, and endures careful testing and bug-fixing
141 142 143 144 145 146 147
until this branch is considered good enough to become a stable
release. The `testing` branch is then merged into the `stable` and
`master` ones, images built and shipped and we go back to code shiny
new stuff in the `devel` branch.

Please note that the `testing` branch generally has not been granted
the same testing and attention as code that has made it into a
148
stable release: please use it for testing purposes but do not rely
149 150
on it for anything. No guarantee, blablabla.

151
#### devel
152

153
Most of the development work that is done in Tails, is done in the
154 155 156 157 158 159 160 161
`devel` branch. This branch will never get released; instead, code
from it will be merged into testing and then into a real release.

Please note that the `devel` branch can be broken, have awful security
problems and so on. No guarantee, blablabla.

The `master` branch is merged into `devel` from time to time.

162
#### Topic branches
163

164
We use topic branches called `bugfix/*` and
165 166 167 168 169 170
`feature/*`, respectively aimed at fixing a single bug and
implementing a single new feature. Once ready, a topic branch is
merged (with `--no-ff`) into the appropriate branch (generally
`devel`). Until it has been merged, a topic branch's history may be
rewritten, e.g. it may be rebased on top of `devel`.

171 172
Unless there are good reasons to do otherwise, bugfix branches must be
forked off the latest stable release tag, while feature branches
bertagaz's avatar
bertagaz committed
173
should be forked off the devel branch.
174

175 176
If you intend to work on a branch not really meant to be proposed to a
merge at first, like an experimenting branch that you still want to push
177 178 179 180 181
to share with other developers, you can prefix its name by the keyword
`wip/`.  It will make it clear to everyone that this branch shouldn't be
merged before being renamed, and our Jenkins instance will not build nor
test it, so you won't get notifications for a branch that you know is
breaking the build and/or the test suite.
182

183 184 185 186 187 188 189 190 191 192 193 194
Promotion material
------------------

This repository contains Tails [[promotion
material|contribute/how/promote/material]].

Anyone can check it out like this:

	git clone https://git-tails.immerda.ch/promotion-material

Developers with write access to the repositories should instead:

195
	git clone boum_org_amnesia@webmasters.boum.org:promotion-material.git
196 197 198 199

We have a [web interface](https://git-tails.immerda.ch/promotion-material/)
available for the promotion material repository.

Tails developers's avatar
Tails developers committed
200 201
<a id="puppet"></a>

202
Puppet modules
203
--------------
204

205 206 207
Those who have SSH access to these repositories must configure their
SSH client a bit, e.g.:

Tails developers's avatar
Tails developers committed
208
	Host git.puppet.tails.boum.org
209 210 211
		HostName d53ykjpeekuikgoq.onion
		ProxyCommand torsocks monkeysphere ssh-proxycommand %h %p

212
### tails
213

Tails developers's avatar
Tails developers committed
214
This is the main *public* Puppet module to manage Tails infrastructure,
215 216 217 218
including classes such as `tails::reprepro` and `tails::whisperback::relay`.

Anyone can check it out like this:

Tails developers's avatar
Tails developers committed
219
	git clone git://git.puppet.tails.boum.org/puppet-tails
220 221 222

Developers with write access to the repositories should instead:

223 224
	git clone gitolite@git.puppet.tails.boum.org:puppet-tails

225 226 227 228 229
### Other Puppet modules

We use and publish a lot of other Puppet modules. See the section
about our [[other repositories|git#other-repositories]].

230
### tails_lizard_manifests
231 232 233 234

Developers with access to the APT secrets can check it out like this:

	git clone gitolite@git.puppet.tails.boum.org:puppet-lizard-manifests
235

236
### tails_secrets_apt
237

238 239 240
Developers with access to the APT secrets can check it out like this:

	git clone gitolite@git.puppet.tails.boum.org:puppet-tails_secrets_apt
241

242
### tails_secrets_whisperback
243

244 245 246
Developers with access to the WhisperBack secrets can check it out like this:

	git clone gitolite@git.puppet.tails.boum.org:puppet-tails_secrets_whisperback
247

Tails developers's avatar
Tails developers committed
248 249
<a id="other-repositories"></a>

250 251 252 253 254
Other repositories
------------------

All other public Tails Git repositories are at
<https://git-tails.immerda.ch/>.
255

256
Unauthenticated access is of the form:
257

258
	git clone https://git-tails.immerda.ch/$REPOSITORY
259 260 261

Developers with write access to the repositories should instead:

Tails developers's avatar
Tails developers committed
262
	git clone tails@git.tails.boum.org:$REPOSITORY
263 264 265 266 267 268 269 270 271 272 273 274 275 276 277 278 279 280 281 282 283 284

<a id="submodules"></a>

Submodules
==========

We use Git submodules to track external repositories from the main
Tails source tree.

The main practical consequence thereof so far, for most Tails
contributors, is that one should generally run the following command
after checking out a branch:

	git submodule update --init

For more information, see:

* the [chapter about
  submodules](https://git-scm.herokuapp.com/book/en/v2/Git-Tools-Submodules)
  in the *Pro Git* book;
* the [`git-submodule(1)`](http://manpages.debian.org/git-submodule)
  man page.