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
|
Contributing
============
Thanks for wanting to contribute to Home Manager! These are some
guidelines to make the process as smooth as possible for both you and
the Home Manager developers.
If you are only looking to report a problem then it is sufficient to
read through the following section on reporting issues. If you instead
want to directly contribute improvements and additions then please
have a look at everything here.
Reporting an issue
------------------
If you notice a problem with Home Manager and want to report it then
have a look among the already [open issues][], if you find one
matching yours then feel free to comment on it to add any additional
information you may have.
If no matching issue exists then go to the [new issue][] page and
write a description of your problem. Include as much information as
you can, ideally also include relevant excerpts from your Home Manager
configuration.
Contributing code
-----------------
If you want to contribute code to improve Home Manager then please
follow these guidelines.
### Fork and create a pull request ###
If you have not previously forked Home Manager then you need to do
that first. Have a look at GitHub's "[Fork A Repo][]" for instructions
on how to do this.
Once you have a fork of Home Manager you should create a branch
starting at the most recent `master`. Give your branch a reasonably
descriptive name. Perform your changes on this branch and when you are
happy with the result push the branch to GitHub and
[create a pull request][].
Assuming your clone is at `$HOME/devel/home-manager` then you can make
the `home-manager` command use it by either
1. overriding the default path by using the `-I` command line option:
home-manager -I home-manager=$HOME/devel/home-manager
or
2. changing the default path by ensuring your configuration includes
programs.home-manager.enable = true;
programs.home-manager.path = "$HOME/devel/home-manager";
and running `home-manager switch` to activate the change.
Afterwards, `home-manager build` and `home-manager switch` will
use your cloned repository.
The first option is good if you only temporarily want to use your
clone.
### Commits ###
The commits in your pull request should be reasonably self-contained,
that is, each commit should make sense in isolation. In particular,
you will be asked to amend any commit that introduces syntax errors or
similar problems even if they are fixed in a later commit.
The commit messages should follow the format
{component}: {description}
{long description}
where `{component}` refers to the code component (or module) your
change affects, `{description}` is a brief description of your change,
and `{long description}` is an optional clarifying description. Note,
`{description}` should start with a lower case letter. As a rare
exception, if there is no clear component, or your change affects many
components, then the `{component}` part is optional.
When adding a new module, say `foo.nix`, we use the fixed commit
format `foo: add module`. You can, of course, still include a long
description if you wish.
In addition to the above commit message guidelines, try to follow the
[seven rules][] as much as possible.
### Style guidelines ###
The code in Home Manager is formatted by the [nixfmt][] tool and the
formatting is checked in the pull request tests. Run the `format` tool
inside the project repository before submitting your pull request.
Note, we prefer `lowerCamelCase` for variable and attribute names with
the accepted exception of variables directly referencing packages in
Nixpkgs which use a hyphenated style. For example, the Home Manager
option `services.gpg-agent.enableSshSupport` references the
`gpg-agent` package in Nixpkgs.
### News ###
Home Manager includes a system for presenting news to the user. When
making a change you, therefore, have the option to also include an
associated news entry. In general, a news entry should only be added
for truly noteworthy news. For example, a bug fix or new option does
generally not need a news entry.
If you do have a change worthy of a news entry then please add one in
[`news.nix`][] but you should follow some basic guidelines:
- The entry timestamp should be in ISO-8601 format having "+00:00" as
time zone. For example, "2017-09-13T17:10:14+00:00". A suitable
timestamp can be produced by the command
date --iso-8601=second --universal
- The entry condition should be as specific as possible. For example,
if you are changing or deprecating a specific option then you could
restrict the news to those users who actually use this option.
- Wrap the news message so that it will fit in the typical terminal,
that is, at most 80 characters wide. Ideally a bit less.
- Unlike commit messages, news will be read without any connection to
the Home Manager source code. It is therefore important to make the
message understandable in isolation and to those who do not have
knowledge of the Home Manager internals. To this end it should be
written in more descriptive, prose like way.
- If you refer to an option then write its full attribute path. That
is, instead of writing
> The option 'foo' has been deprecated, please use 'bar' instead.
it should read
> The option 'services.myservice.foo' has been deprecated, please
> use 'services.myservice.bar' instead.
- A new module, say `foo.nix`, should always include a news entry
that has a message along the lines of
> A new module is available: 'services.foo'.
If the module is platform specific, e.g., a service module using
systemd, then a condition like
```
condition = hostPlatform.isLinux;
```
should be added.
[open issues]: https://github.com/rycee/home-manager/issues
[new issue]: https://github.com/rycee/home-manager/issues/new
[Fork A Repo]: https://help.github.com/articles/fork-a-repo/
[create a pull request]: https://help.github.com/articles/creating-a-pull-request/
[seven rules]: https://chris.beams.io/posts/git-commit/#seven-rules
[`news.nix`]: https://github.com/rycee/home-manager/blob/master/modules/misc/news.nix
[nixfmt]: https://github.com/serokell/nixfmt/
|
