Navigation Menu

Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

nixos/manual: rename "Configuration Syntax" section to "Options Management" [WIP] #57675

Closed
wants to merge 2 commits into from

Conversation

aaronjanse
Copy link
Member

Motivation for this change

The current sections under Section II: Configuration of the NixOS Manual are as follows:

5. Configuration Syntax
    5.1. NixOS Configuration File
    5.2. Abstractions
    5.3. Modularity
    5.4. Syntax Summary
6. Package Management
    6.1. Declarative Package Management
        6.1.1. Customising Packages
        6.1.2. Adding Custom Packages
    6.2. Ad-Hoc Package Management
7. User Management
8. [...]

I propose changing the title of the "Configuration Syntax" section to "Options Management."

Although renaming the section involves some minor changes to its contents, this should make its contents much more easily discovered by new users of NixOS reading the Table of Contents.

In addition to better matching the contents of the section, it would allow for new sub-sections to be made in the future to further document the options management process, since the currently-named "Configuration Syntax" section is the best place in the manual to do so.

The reason for proposing this is #49899: better document nixos-options. If we rename this section, it would allow us to, in the future, add a subsection to specifically document accessing option values, among other things.

Most of the contents for a hypothetical "Accessing Option Values" section values is already written, found in [5.3 Modularity]. A dedicated section in the future would allow for further elaboration along with being more discoverable for readers who have not read the manual from start to finish (i.e. most, if not all, non-advanced users of NixOS, I assume).

Things done
  • Tested using sandboxing (nix.useSandbox on NixOS, or option sandbox in nix.conf on non-NixOS)
  • Built on platform(s)
    • NixOS
    • macOS
    • other Linux distributions
  • Tested via one or more NixOS test(s) if existing and applicable for the change (look inside nixos/tests)
  • Tested compilation of all pkgs that depend on this change using nix-shell -p nox --run "nox-review wip"
  • Tested execution of all binary files (usually in ./result/bin/)
  • Determined the impact on package closure size (by running nix path-info -S before and after)
  • Assured whether relevant documentation is up to date
  • Fits CONTRIBUTING.md.

Since this is a non-minor change, I assume that I will likely have to make some changes based on feedback, assuming this is eligible for being merged at all. Because of this, I marked the title with [WIP]

@stale
Copy link

stale bot commented Jun 1, 2020

Thank you for your contributions.
This has been automatically marked as stale because it has had no activity for 180 days.
If this is still important to you, we ask that you leave a comment below. Your comment can be as simple as "still important to me". This lets people see that at least one person still cares about this. Someone will have to do this at most twice a year if there is no other activity.
Here are suggestions that might help resolve this more quickly:

  1. Search for maintainers and people that previously touched the
    related code and @ mention them in a comment.
  2. Ask on the NixOS Discourse. 3. Ask on the #nixos channel on
    irc.freenode.net.

@stale stale bot added the 2.status: stale https://github.com/NixOS/nixpkgs/blob/master/.github/STALE-BOT.md label Jun 1, 2020
@stale stale bot removed the 2.status: stale https://github.com/NixOS/nixpkgs/blob/master/.github/STALE-BOT.md label Oct 3, 2020
@ryantm ryantm marked this pull request as draft October 23, 2020 03:08
@aaronjanse aaronjanse closed this Dec 5, 2020
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Projects
None yet
Development

Successfully merging this pull request may close these issues.

None yet

4 participants