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