From 3b5fee627cc5b23413bb527f01cc8e4569247578 Mon Sep 17 00:00:00 2001 From: Valentin Gagarin Date: Mon, 5 Feb 2024 13:42:29 +0100 Subject: [PATCH] update contributing guides - clarify a few phrases - move Open Collective link to the top - add section headings for easier navigation - add a few details on contacting people --- source/conf.py | 2 +- source/contributing/documentation/index.md | 2 +- source/contributing/how-to-contribute.md | 22 ++++++++------- source/contributing/how-to-get-help.md | 32 ++++++++++++++++------ source/index.md | 1 + 5 files changed, 38 insertions(+), 21 deletions(-) diff --git a/source/conf.py b/source/conf.py index 89a6c33..ea81a12 100644 --- a/source/conf.py +++ b/source/conf.py @@ -78,7 +78,7 @@ master_doc = "index" # General information about the project. project = "nix.dev" -author = "the nix.dev contributors." +author = "the Nix documentation team and contributors." copyright = "2016-" + str(date.today().year) + ", NixOS Foundation" # The version info for the project you're documenting, acts as replacement for diff --git a/source/contributing/documentation/index.md b/source/contributing/documentation/index.md index e1910be..bbbaac0 100644 --- a/source/contributing/documentation/index.md +++ b/source/contributing/documentation/index.md @@ -5,7 +5,7 @@ Documentation contributions should follow the [style guide](./style-guide.md). Feel free to get in touch with the [Nix documentation team](https://nixos.org/community/teams/documentation) if you want to help out. -:::{attention} +:::{important} If you cannot contribute time, consider [donating to the NixOS Foundation's documentation project on Open Collective](https://opencollective.com/nixos/projects/documentation-project) to fund ongoing maintenance and development of reference documentation and learning materials. ::: diff --git a/source/contributing/how-to-contribute.md b/source/contributing/how-to-contribute.md index 041fe9e..6792fc6 100644 --- a/source/contributing/how-to-contribute.md +++ b/source/contributing/how-to-contribute.md @@ -6,6 +6,13 @@ Keeping it working and up to date – and improving it continuously – would no This guide shows how you can contribute to {term}`Nix`, {term}`Nixpkgs` or {term}`NixOS`. +:::{important} +If you cannot contribute time, consider [donating to the NixOS Foundation on Open Collective](https://opencollective.com/nixos). + +Currently the focus is on funding in-person events to share knowledge and grow the community of developers proficient with Nix. +With enough budget, it would be possible to pay for ongoing maintenance and development of critical infrastructure and code – demanding work that we cannot expect to be done by volunteers indefinitely. +::: + ## Getting started Start with asking informed questions, after reading reference documentation and the code relevant to what you care about. @@ -25,22 +32,17 @@ This is where we need the most help and where it is the easiest to begin. Documentation and contribution guides are often incomplete or outdated, much as we would like them to be otherwise. We're working on it. You can help and improve the situation for everyone by immediately solving problems with the contribution workflow as you encounter them. -While this may slow you down with addressing your original concern, it will make it a lot easier for anyone to make meaningful contributions in the future, and lead to better code and documentation in the long run. - -:::{attention} -If you cannot contribute time, consider [donating to the NixOS Foundation on Open Collective](https://opencollective.com/nixos). - -Currently the focus is on funding in-person events to share knowledge and grow the community of developers proficient with Nix. -With enough budget, it would be possible to pay for ongoing maintenance and development of critical infrastructure and code – demanding work that we cannot expect to be done by volunteers indefinitely. -::: +This may slow you down with addressing your original concern. +But it will make it a lot easier for anyone to make meaningful contributions in the future. +And it will lead to better code and documentation in the long run. ## Report an issue We can only fix issues that we know of, so please report any issue you encounter. -- Issues with {term}`Nix` (including the [Nix reference manual](https://nixos.org/manual/nix/stable)) are reported at . +- Report issues with {term}`Nix` (including the [Nix reference manual](https://nixos.org/manual/nix/stable)) at . -- Issues with {term}`Nixpkgs` or {term}`NixOS` (including packages, configuration modules, the [Nixpkgs manual](https://nixos.org/manual/nixpkgs/stable), and the [NixOS manual](https://nixos.org/manual/nixos/stable)) are reported at . +- Report issues with {term}`Nixpkgs` or {term}`NixOS` (including packages, configuration modules, the [Nixpkgs manual](https://nixos.org/manual/nixpkgs/stable), and the [NixOS manual](https://nixos.org/manual/nixos/stable)) at . Make sure that there is not already an open issue for your problem. Please follow the issue template and fill in all requested information. diff --git a/source/contributing/how-to-get-help.md b/source/contributing/how-to-get-help.md index 9f61484..50e4344 100644 --- a/source/contributing/how-to-get-help.md +++ b/source/contributing/how-to-get-help.md @@ -3,40 +3,54 @@ If you need assistance with one of your contributions, there are a few places you can go for help. -For better efficiency and chances of success, you should try contacting individuals or -groups with more specific knowledge first: +## How to find maintainers + +For better efficiency and higher chance of success, you should try contacting individuals or groups with more specific knowledge first: - If your contribution is for a package in Nixpkgs, look for its maintainers in the [`maintainers`](https://nixos.org/manual/nixpkgs/stable/#var-meta-maintainers) attribute. -- Check out if any teams are responsible for the relevant subsystem: +- Check if any teams are responsible for the relevant subsystem: - On the [NixOS website](https://nixos.org/community/#governance-teams). - In the [list of Nixpkgs maintainer teams](https://github.com/NixOS/nixpkgs/blob/master/maintainers/team-list.nix). - In the `CODEOWNERS` files for [Nixpkgs](https://github.com/NixOS/nixpkgs/blob/master/.github/CODEOWNERS) or [Nix](https://github.com/NixOS/nix/blob/master/.github/CODEOWNERS). -- Look at the [git log](https://www.git-scm.com/docs/git-log) for the files you need help - with, and take note of the email addresses of people who committed. +- Check the output of [`git blame`](https://git-scm.com/docs/git-blame) or [`git log`](https://www.git-scm.com/docs/git-log) for the files you need help with. + Take note of the email addresses of people who committed relevant code. -Once you've found the people you're looking for, you can contact them via: +## Which communication channels to use + +Once you've found the people you're looking for, you can contact them on one of the following platforms: - GitHub - [Mention the GitHub username](https://docs.github.com/en/get-started/writing-on-github/getting-started-with-writing-and-formatting-on-github/basic-writing-and-formatting-syntax#mentioning-people-and-teams) found in the [`maintainers-list.nix` file][maintainers-list] in issue or pull request descriptions, or comments. + All the source code is maintained on GitHub. + This is the right place to discuss implementation details. + + In issue comments or pull request descriptions, [mention the GitHub username](https://docs.github.com/en/get-started/writing-on-github/getting-started-with-writing-and-formatting-on-github/basic-writing-and-formatting-syntax#mentioning-people-and-teams) found in the [`maintainers-list.nix` file][maintainers-list]. - [Discourse](https://discourse.nixos.org) + Discourse is used for announcements, coordination, and open-ended questions. + Try the GitHub username found in the [`maintainers-list.nix` file][maintainers-list] to mention or directly contact a specific user. Note that some people use a different username on Discourse. - [Matrix] - Use the Matrix handle found in the [`maintainers-list.nix` file][maintainers-list]. - If no Matrix handle is present for a specific maintainer, try searching for them using their GitHub username, as most people tend to use the same one across channels. + Matrix is used for direct messages and short-lived, timely exchanges. + + To contact a maintainer, use their Matrix handle found in the [`maintainers-list.nix` file][maintainers-list]. + If no Matrix handle is present for a specific maintainer, try searching for their GitHub username, as most people tend to use the same one across channels. + + Maintainer teams usually have their own public Matrix room. - Email Use email addresses found with `git log`. +## Other venues + If you haven't found any specific users or groups that could help you with your contribution, you can resort to asking the community at large, using one of the following official communication channels: diff --git a/source/index.md b/source/index.md index 90d8774..1d6889a 100644 --- a/source/index.md +++ b/source/index.md @@ -10,6 +10,7 @@ myst: # Welcome to nix.dev nix.dev is the home of official documentation for the Nix ecosystem. +It is maintained by the [Nix documentation team](https://nixos.org/community/teams/documentation). If you're new here, {ref}`install Nix ` and begin your journey with our tutorial series!