1# Contributing
 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## Get the source code
 8
 9Clone this repository to your system in a way you're comfortable with. Below, we
10show a command that [clones the repository][how-to-clone] using SSH, and places
11it in `~/code/git-bug`.
12
13```
14git clone git@github.com:MichaelMure/git-bug ~/code/git-bug
15```
16
17> [!IMPORTANT]
18> If you wish to clone the repository to another location on disk, change
19> `~/code/git-bug` to your desired path. The rest of this documentation will
20> refer to `~/code/git-bug` in all instances, so make sure you change them
21> there, too.
22
23## Software recommendations
24
25While you can install Golang and hack on this project on your own, you're likely
26to have a better experience if you install the following software.
27
28### <a name="install-nix"></a> `nix` (_recommended_)
29
30[`nix`][install/nix] is used in this repository to provide a common development
31shell, with a complete set of the appropriate version of the tools used to work
32on `git-bug`.
33
34You can install `nix` by following [the official instructions][install/nix], but
35we recommend adding some additional flags in order to enable some (technically
36experimental, but largely stable) configuration options:
37
38```
39curl -L https://nixos.org/nix/install | sh -s -- --daemon --nix-extra-conf-file <( \
40cat << EOF | sed -e 's/^ *//'
41  experimental-features = nix-command flakes
42EOF
43)
44```
45
46> [!TIP]
47> Make sure you read the prompts from the installation script carefully. After
48> installation, you'll need to start a new shell.
49
50### <a name="install-direnv"></a> `direnv` (_recommended_)
51
52[`direnv`][install/direnv] is used to automatically activate the development
53shell (because of the `.envrc` in the root of this repository).
54
55#### <a name="install-direnv-with-nix"></a> With `nix`
56
57> [!IMPORTANT]
58> If you are not comfortable with `nix`, we recommend [installing `direnv`
59> without nix][install/install-direnv-without-nix].
60
61```
62nix --extra-experimental-options 'flakes nix-command' profile install nixpkgs\#direnv
63```
64
65There's a second step that is critical -- be sure to [configure your
66shell][install/direnv/shell].
67
68#### <a name="install-direnv-without-nix"></a> Without `nix`
69
70You can install `direnv` by following [the official
71instructions][install/direnv]. There's a second step that is critical -- be sure
72to [configure your shell][install/direnv/shell].
73
74After installation, you'll need to start a new shell.
75
76##### <a name="direnv-config"></a> direnv configuration (_recommended_)
77
78If you install `direnv`, it is recommended to set the following configuration
79options to improve your user experience. At the time of writing, these go in
80`~/.config/direnv/direnv.toml`.
81
82This configuration, namely, the `whitelist.exact` property, will ensure that
83`direnv` always automatically sources the `.envrc` in this repository.
84
85```
86hide_env_diff = true
87warn_timeout = 0
88
89[whitelist]
90exact = ["~/code/git-bug/.envrc"]
91```
92
93> [!IMPORTANT]
94> Make sure you change the `~/code/git-bug` portion of the string to the
95> appropriate path (the path that you cloned this repository to on your system).
96
97[install/nix]: https://nix.dev/install-nix
98[install/direnv]: https://github.com/direnv/direnv/blob/master/docs/installation.md
99[install/direnv/shell]: https://github.com/direnv/direnv/blob/master/docs/hook.md