cafkafk/nixpkgs
cafkafk/nixpkgs
1
0
Fork 0
Code Issues Pull requests Projects Releases Packages Wiki Activity Actions 2

CONTRIBUTING.md: Write a new section on how to propose a change

Browse source 
Removing paragraphs from the other sections that aren't necessary anymore
This commit is contained in:
Silvan Mosberger 2023-08-03 00:12:58 +02:00
parent 99c6942d83
commit 67ae88c072
1 changed files with 65 additions and 24 deletions
Show stats Download patch file Download diff file Expand all files Collapse all files

89
CONTRIBUTING.md
View file

@ -16,30 +16,75 @@ This file contains general contributing information, but individual parts also h
- [`doc`](./doc): Sources and infrastructure for the [Nixpkgs manual](https://nixos.org/manual/nixpkgs/stable/)
- [`nixos`](./nixos): Implementation of [NixOS](https://nixos.org/manual/nixos/stable/)
## (Proposing a change) | Submitting changes
## How to propose a change
Note: contributing implies licensing those contributions
under the terms of [COPYING](COPYING), which is an MIT-like license.
This section describes in some detail how changes can be made and proposed with pull requests.
> **Note**
> Be aware that contributing implies licensing those contributions under the terms of [COPYING](./COPYING), an MIT-like license.
0. Set up a local version of Nixpkgs to work with using GitHub and Git
1. [Fork](https://docs.github.com/en/get-started/quickstart/fork-a-repo#forking-a-repository) the [Nixpkgs repository](https://github.com/nixos/nixpkgs/).
1. [Clone the forked repository](https://docs.github.com/en/get-started/quickstart/fork-a-repo#cloning-your-forked-repository) into a local `nixpkgs` directory.
1. [Configure the upstream Nixpkgs repository](https://docs.github.com/en/get-started/quickstart/fork-a-repo#configuring-git-to-sync-your-fork-with-the-upstream-repository).
1. Create and switch to a new Git branch, ideally such that:
- The name of the branch hints at the change you'd like to implement, e.g. `update-hello`.
- The base of the branch includes the most recent changes on the `master` branch.
> **Note**
> Depending on the change you may want to use a different branch, see <!-- TODO link to branch section -->
```bash
# Make sure you have the latest changes from upstream Nixpkgs
git fetch upstream
# Create and switch to a new branch based off the master branch in Nixpkgs
git switch --create update-hello upstream/master
```
To avoid having to download and build potentially many derivations, at the expense of using a potentially outdated version, you can base the branch off a specific [Git commit](https://www.git-scm.com/docs/gitglossary#def_commit) instead:
- The commit of the latest `nixpkgs-unstable` channel, available [here](https://channels.nixos.org/nixpkgs-unstable/git-revision).
- The commit of a local Nixpkgs downloaded using [nix-channel](https://nixos.org/manual/nix/stable/command-ref/nix-channel), available using `nix-instantiate --eval --expr '(import <nixpkgs/lib>).trivial.revisionWithDefault null'`
- If you're using NixOS, the commit of your NixOS installation, available with `nixos-version --revision`.
Once you have an appropriate commit you can use it instead of `upstream/master` in the above command:
```bash
git switch --create update-hello <the desired base commit>
```
2. Make the desired changes in the local Nixpkgs repository using an editor of your choice.
Make sure to:
- Adhere to both the [general code conventions](#code-conventions), and the code conventions specific to the part you're making changes to.
See the [overview section](#overview) for more specific information.
- Test the changes.
See the [overview section](#overview) for more specific information.
- If necessary, document the change.
See the [overview section](#overview) for more specific information.
3. Commit your changes using `git commit`.
Make sure to adhere to the [commit conventions](#commit-conventions).
Repeat the steps 2 and 3 as many times as necessary.
Advance to the next step if all the commits (viewable with `git log`) make sense together.
4. Push your commits to your fork of Nixpkgs.
```
git push --set-upstream origin HEAD
```
The above command will output a link that allows you to directly quickly do the next step:
```
remote: Create a pull request for 'update-hello' on GitHub by visiting:
remote: https://github.com/myUser/nixpkgs/pull/new/update-hello
```
5. [Create a pull request](https://docs.github.com/en/pull-requests/collaborating-with-pull-requests/proposing-changes-to-your-work-with-pull-requests/creating-a-pull-request#creating-the-pull-request) from the new branch in your Nixpkgs fork to the upstream Nixpkgs repository.
Generally you should use `master` as the pull requests base branch.
See <!-- TODO branch section link --> for when a different branch should be used instead.
Make sure to go through the [pull request template](#pull-request-template) in the pre-filled default description.
### Making patches {#submitting-changes-making-patches}
- Read [Manual (How to write packages for Nix)](https://nixos.org/nixpkgs/manual/).
- Fork [the Nixpkgs repository](https://github.com/nixos/nixpkgs/) on GitHub.
- Create a branch for your future fix.
- You can make branch from a commit of your local `nixos-version`. That will help you to avoid additional local compilations. Because you will receive packages from binary cache. For example
```ShellSession
$ nixos-version --hash
0998212
$ git checkout 0998212
$ git checkout -b 'fix/pkg-name-update'
```
- Please avoid working directly on the `master` branch.
- If you removed pkgs or made some major NixOS changes, write about it in the release notes for the next stable release. For example `nixos/doc/manual/release-notes/rl-2003.xml`.
- Test your changes. If you work with
@ -64,10 +109,6 @@ under the terms of [COPYING](COPYING), which is an MIT-like license.
### (Creating a pull request)
- Push your changes to your fork of nixpkgs.
- Create the pull request
- Follow [the contribution guidelines](https://github.com/NixOS/nixpkgs/blob/master/CONTRIBUTING.md#submitting-changes).
When pull requests are made, our tooling automation bot,
[OfBorg](https://github.com/NixOS/ofborg) will perform various checks
to help ensure expression quality.