1# Contributing <a name="contributing"></a>
2
3:wave: Hey there! Thanks for considering taking the time to contribute to
4`git-bug`. This page contains some general guidelines, and instructions for
5getting started as a contributor to this project.
6
7<!-- mdformat-toc start --slug=github --maxlevel=4 --minlevel=2 -->
8
9- [Get the source code](#get-the-source-code)
10- [Software requirements](#software-requirements)
11 - [1.0 | Install nix](#10--install-nix)
12 - [2.0 | Enable `nix-command` and `flakes`](#20--enable-nix-command-and-flakes)
13 - [3.0 | Install and configure `direnv`](#30--install-and-configure-direnv)
14- [4.0 | Post-installation tasks](#40--post-installation-tasks)
15 - [4.1 | Open a new shell](#41--open-a-new-shell)
16 - [4.2 | Test the development shell](#42--test-the-development-shell)
17- [Useful development commands](#useful-development-commands)
18- [Submitting changes](#submitting-changes)
19
20<!-- mdformat-toc end -->
21
22## Get the source code<a name="get-the-source-code"></a>
23
24Clone this repository to your system in a way you're comfortable with. Below, we
25show a command that clones the repository using SSH, and places it in
26`~/code/git-bug`.
27
28```
29git clone git@github.com:git-bug/git-bug ~/code/git-bug
30```
31
32> [!TIP]
33> If you wish to clone the repository to another location on disk, change
34> `~/code/git-bug` to your desired path (e.g. your current directory can be used
35> with `.` or by omitting the path argument). The rest of this documentation
36> will refer to `~/code/git-bug` in all instances, so make sure you change them
37> there to match the location you've cloned the repository.
38
39## Software requirements<a name="software-requirements"></a>
40
41This repository uses `nix` to provide a consistent development environment,
42ensuring that each contributor has the same revision of each dependency and tool
43installed. It is **strongly** encouraged to use `nix` when contributing to
44`git-bug` to remove the "it works on my machine" class of errors, and ensure you
45have a smoother experience passing the CI pipelines (wrt formatting and such).
46
47While you can manually install the [tools and packages we use](./flake.nix) and
48hack on this project on your own, you will miss out on the hermeticity and
49standardization that our development shell provides. You may end up fighting
50with failing CI pipelines more often, or have to figure out how to perform
51various tasks on your own. Using the development shell ensures you always have
52every tool you need to contribute to `git-bug`, and that each tool is always
53configured correctly.
54
55Because of this, we encourage all contributors to follow the documentation below
56to install the dependencies for the development shell.
57
58> [!NOTE]
59> In the future, we will provide a container image with `nix` pre-installed and
60> everything configured to get you started. This will be able to be pulled like
61> any other image, and will be made compatible with VSCode's "devcontainer"
62> feature and GitHub Codespaces.
63>
64> For more information, see the [tracking issue][issue/1364].
65
66______________________________________________________________________
67
68### 1.0 | Install nix<a name="10--install-nix"></a>
69
70To install `nix`, you can follow [the official instructions][install/nix].
71
72We recommend following the instructions for `multi-user mode` where applicable,
73instead of `single-user mode`.
74
75> [!IMPORTANT]
76> The rest of this document assumes you have successfully installed `nix`.
77
78______________________________________________________________________
79
80### 2.0 | Enable `nix-command` and `flakes`<a name="20--enable-nix-command-and-flakes"></a>
81
82`nix-command` and `flakes` are two optional configuration properties that we
83depend on in order to provide the development shell. You'll need to make sure
84that these are enabled.
85
86<details>
87<summary><strong>NixOS</strong></summary>
88
89Add the following to your system configuration:
90
91<pre>
92nix.settings.experimental-features = [ "nix-command" "flakes" ];
93</pre>
94
95</details>
96
97<details>
98<summary><strong>Other</strong></summary>
99
100Add the following to `~/.config/nix.conf` or `/etc/nix/nix.conf`:
101
102<pre>
103experimental-features = nix-command flakes
104</pre>
105
106</details>
107
108> [!IMPORTANT]
109> The rest of this document assume you have enabled these options.
110
111______________________________________________________________________
112
113### 3.0 | Install and configure `direnv`<a name="30--install-and-configure-direnv"></a>
114
115[`direnv`][install/direnv] can be used to automatically activate the development
116shell (using [`//:.envrc`][envrc]). It can be installed either with `nix`, or
117independently.
118
119<details>
120<summary><strong>With nix</strong> <em>(suggested for users new to nix)</em></summary>
121
122<pre>
123nix --extra-experimental-options 'flakes nix-command' profile install nixpkgs\#direnv
124</pre>
125
126Next, run the following commands to apply the **optional** configuration for
127direnv. Be sure to change references to `~/code/git-bug` if you have cloned the
128repository somewhere else.
129
130<strong>Create a configuration file for <code>direnv</code></strong>
131
132<pre>touch ~/.config/direnv/direnv.toml</pre>
133
134<strong>Disable the warning for shells with longer load times</strong>
135
136_This is optional, but recommended, as it helps reduce visual clutter._
137
138<pre>
139nix run nixpkgs\#dasel -- -r toml -f ~/.config/direnv/direnv.toml \
140 put -t int -v 0 ".global.warn_timeout"
141</pre>
142
143<strong>Disable printing of the environment variables that change</strong>
144
145_This is optional, but recommended, as it helps reduce visual clutter._
146
147<pre>
148nix run nixpkgs\#dasel -- -r toml -f ~/.config/direnv/direnv.toml \
149 put -t bool -v true ".global.hide_env_diff"
150</pre>
151
152<strong>Configure automatic activation of the development shell</strong>
153
154_This is optional, but strongly recommended._
155
156<pre>
157nix run nixpkgs\#dasel -- -r toml -f ~/.config/direnv.toml \
158 put -v "~/code/git-bug/.envrc" ".whitelist.exact[]"
159</pre>
160
161Alternatively, simply run `direnv allow` after moving into the repository for
162the first time.
163
164> **IMPORTANT**<br /> If you choose not to allow the shell to be automatically
165> activated, you will need to type `nix develop` every time you want to activate
166> it, and this will swap you into bash and change your prompt. You'll have a far
167> better experience allowing `direnv` to automatically manage activation and
168> deactivation.
169
170<strong>Configure your shell</strong>
171
172This final step is crucial -- be sure to
173[configure your shell][install/direnv/shell] for direnv.
174
175</details>
176
177<details>
178<summary><strong>Using <code>home-manager</code></strong></summary>
179
180<pre>
181programs.direnv = {
182 enable = true;
183 nix-direnv.enable = true;
184
185 # one of the following, depending on your shell
186 # enableZshIntegration = true;
187 # enableBashIntegration = true;
188 # enableFishIntegration = true;
189 # enableNushellIntegration = true;
190
191 config = {
192 hide_env_diff = true;
193 warn_timeout = 0;
194
195 whitelist.exact = [ "~/code/git-bug/.envrc" ];
196 };
197}
198</pre>
199
200</details>
201
202______________________________________________________________________
203
204## 4.0 | Post-installation tasks<a name="40--post-installation-tasks"></a>
205
206Congratulations! If you've reached this section of the documentation, chances
207are that you have a working development environment for contributing to this
208repository. Read below for some additional tasks you should complete.
209
210### 4.1 | Open a new shell<a name="41--open-a-new-shell"></a>
211
212In order for the installation to take effect, you will need to open a new shell.
213It is recommended to do this and complete the test (described below) prior to
214closing the shell you ran the installation script in, just in case you run into
215issues and need to refer to any output it provided.
216
217### 4.2 | Test the development shell<a name="42--test-the-development-shell"></a>
218
219To test that the development shell is active, you will need to move to the
220repository's directory. If you installed and properly configured `direnv` for
221automatic activation, the shell should activate upon changing directories.
222
223```
224{ test -n "$IN_NIX_SHELL" && echo "ACTIVE"; } || echo "INACTIVE"
225```
226
227If you have activated the development shell, you will see `ACTIVE` printed to
228the console. If you have not, you will see `INACTIVE` printed to the console.
229
230______________________________________________________________________
231
232## Useful development commands<a name="useful-development-commands"></a>
233
234- `make build` - build `git-bug` and output the binary at `./git-bug`
235 - `make build/debug` - build a debugger-friendly binary
236- `make install` - build `git-bug`, and install it to `$GOPATH/bin`
237- `nix fmt` - format everything (configured in [`//:treefmt.nix`][treefmt])
238 - `nix fmt <path...>` to restrict the scope to given directories or files
239 - _see `nix fmt --help` for more information_
240- `nix flake check` to run lint/format checks and all tests defined in
241 `//nix/checks`
242- `go generate` - generate cli documentation and shell completion files
243 - this is automatically executed by many `make` targets, e.g. `make build`
244- `go test ./commands -update` - update golden files used in tests
245 - this is _required_ when changing the output of CLI commands, if the files in
246 `//commands/testdata/...` do not match the new output format
247- `pinact` to pin any newly-added github action libraries
248 - `pinact upgrade` to upgrade action libraries
249
250> [!NOTE]
251> There is an ongoing effort to simplify the commands you need to call in our
252> environment, with a trend toward `nix`, while `make` may continue to be
253> supported for common workflows (e.g. building a release binary).
254
255## Submitting changes<a name="submitting-changes"></a>
256
257You can submit your changes in the typical fork-based workflow to this
258repository on GitHub. That is: fork this repository, push to a branch to your
259repository, and create a pull request.
260
261If you are in the development shell, you have the `gh` command line tool
262available for use with github.
263
264______________________________________________________________________
265
266##### See more
267
268- [View the commit message guidelines][doc/contrib/commit]
269- [An overview of the architecture][doc/design/arch]
270- [Learn about the data model][doc/design/model]
271- [See how to create a new entity][example-entity]
272
273[doc/contrib/commit]: ./doc/contrib/commit-message-guidelines.md
274[doc/design/arch]: ./doc/design/architecture.md
275[doc/design/model]: ./doc/design/data-model.md
276[envrc]: ./.envrc
277[example-entity]: ./entity/dag/example_test.go
278[install/direnv]: https://github.com/direnv/direnv/blob/master/docs/installation.md
279[install/direnv/shell]: https://github.com/direnv/direnv/blob/master/docs/hook.md
280[install/nix]: https://nix.dev/install-nix
281[issue/1364]: https://github.com/git-bug/git-bug/issues/1364
282[treefmt]: ./treefmt.nix