mirror of
https://github.com/nix-community/home-manager.git
synced 2025-11-22 10:19:39 +01:00
d094c6763c
The current way to define a news entry in Home-Manager is error prone (since you need to type the date manually) and also it is common cause of conflicts after merges because all entries are defined in the same file. This commit fixes this: we can now create individual news entries for each new entry. A script `create-news-entry.sh` also helps to create it in the correct format (with the correct filenames and structure).
60 lines
2.3 KiB
Markdown
60 lines
2.3 KiB
Markdown
# News {#sec-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`](https://github.com/nix-community/home-manager/blob/master/modules/misc/news.nix)
|
|
but you should follow some basic guidelines:
|
|
|
|
- Use the included
|
|
[`create-news-entry.sh`](https://github.com/nix-community/home-manager/blob/master/modules/misc/news/create-news-entry.sh)
|
|
script to generate a news entry file:
|
|
|
|
``` shell
|
|
$ modules/misc/news/create-news-entry.sh
|
|
```
|
|
|
|
this will create a new file inside `modules/misc/news` directory
|
|
with some placeholder information that you can edit.
|
|
|
|
- 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
|
|
|
|
``` nix
|
|
condition = hostPlatform.isLinux;
|
|
```
|
|
|
|
should be added. If you contribute a module then you don't need to
|
|
add this entry, the merger will create an entry for you.
|