CONTRIBUTING: expand contributor and reviewer guidelines
Document the full contribution workflow including feature branches, README/flake.nix entry formats, testing from forks, deprecation process, and update reviewer section to use GitHub merge queues. Also clarify that any nixpkgs committer can review PRs.
This commit is contained in:
Jörg Thalheim
parent
cce68f4a54
commit
0ac0225d16
2 changed files with 140 additions and 6 deletions
2
.github/PULL_REQUEST_TEMPLATE.md
vendored
2
.github/PULL_REQUEST_TEMPLATE.md
vendored
|
|
@ -1,3 +1,5 @@
|
|||
<!-- Please read the CONTRIBUTING.md guidelines before submitting: https://github.com/NixOS/nixos-hardware/blob/master/CONTRIBUTING.md -->
|
||||
|
||||
###### Description of changes
|
||||
|
||||
|
||||
|
|
|
|||
144
CONTRIBUTING.md
144
CONTRIBUTING.md
|
|
@ -1,5 +1,11 @@
|
|||
# Contributing a Device Profile
|
||||
|
||||
Please submit your contributions from a feature branch, not from your master branch:
|
||||
|
||||
```bash
|
||||
git checkout -b my-new-hardware-profile
|
||||
```
|
||||
|
||||
## 1. Writing profiles
|
||||
|
||||
Create an appropriate directory and start writing your expression.
|
||||
|
|
@ -36,18 +42,144 @@ should either be conservative or be guarded behind additional NixOS module
|
|||
options. If it makes sense to have a performance-focussed config, it can be
|
||||
declared in a separate profile.
|
||||
|
||||
## 2. Adding Entry
|
||||
## 2. Optional: Add a README
|
||||
|
||||
Link the profile in the table in README.md and in flake.nix.
|
||||
Profiles can include a `README.md` with device-specific documentation such as:
|
||||
- Firmware update instructions
|
||||
- BIOS settings
|
||||
- Known issues and workarounds
|
||||
- Links to external resources
|
||||
|
||||
## 3. Testing
|
||||
See [framework/13-inch/7040-amd/README.md](framework/13-inch/7040-amd/README.md)
|
||||
for a good example.
|
||||
|
||||
Run `nix run .#run-tests` to evaluate all hardware profiles.
|
||||
## 3. Adding Entry
|
||||
|
||||
Add your profile to both `README.md` and `flake.nix`.
|
||||
|
||||
**README.md**: Add a row to the table in alphabetical order by manufacturer:
|
||||
|
||||
```markdown
|
||||
| [Manufacturer Model](manufacturer/model) | `<nixos-hardware/manufacturer/model>` | `manufacturer-model` |
|
||||
```
|
||||
|
||||
The columns are:
|
||||
1. Model name linking to the profile directory
|
||||
2. Channel path (for `imports = [ <nixos-hardware/...> ]`)
|
||||
3. Flake module name (for `nixos-hardware.nixosModules.<name>`)
|
||||
|
||||
**flake.nix**: Add an entry to the `nixosModules` attribute set:
|
||||
|
||||
```nix
|
||||
manufacturer-model = import ./manufacturer/model;
|
||||
```
|
||||
|
||||
The flake module name should use hyphens (e.g., `dell-xps-15-9500`).
|
||||
|
||||
## 4. Multiple Variants
|
||||
|
||||
For devices with multiple configurations (e.g., different GPU options), create
|
||||
subdirectories with a shared base module. For example:
|
||||
|
||||
```
|
||||
dell/xps/15-9560/
|
||||
├── default.nix # Base profile (or one default variant)
|
||||
├── intel/default.nix # Intel-only variant
|
||||
├── nvidia/default.nix # Nvidia variant
|
||||
└── xps-common.nix # Shared configuration
|
||||
```
|
||||
|
||||
Each variant needs its own entry in README.md and flake.nix:
|
||||
|
||||
```nix
|
||||
dell-xps-15-9560 = import ./dell/xps/15-9560;
|
||||
dell-xps-15-9560-intel = import ./dell/xps/15-9560/intel;
|
||||
dell-xps-15-9560-nvidia = import ./dell/xps/15-9560/nvidia;
|
||||
```
|
||||
|
||||
## 5. Testing
|
||||
|
||||
Before opening a pull request, test your profile by pointing to your fork.
|
||||
|
||||
**Using channels:**
|
||||
|
||||
```bash
|
||||
sudo nix-channel --add https://github.com/<github-user>/nixos-hardware/archive/<branch>.tar.gz nixos-hardware
|
||||
sudo nix-channel --update
|
||||
sudo nixos-rebuild test
|
||||
```
|
||||
|
||||
**Using flakes:**
|
||||
|
||||
Update your `flake.nix` input temporarily:
|
||||
|
||||
```nix
|
||||
inputs.nixos-hardware.url = "github:<github-user>/nixos-hardware/<branch>";
|
||||
```
|
||||
|
||||
Then run:
|
||||
|
||||
```bash
|
||||
sudo nixos-rebuild test --flake .
|
||||
```
|
||||
|
||||
You can also run `nix run .#run-tests` to evaluate all hardware profiles.
|
||||
Because profiles can only be tested with the appropriate hardware, quality
|
||||
assurance is up to *you*.
|
||||
|
||||
## Compatibility
|
||||
|
||||
Profiles should work with both NixOS unstable and the current stable release.
|
||||
|
||||
## Deprecating Modules
|
||||
|
||||
When renaming or removing a module, add deprecation warnings for both flake and
|
||||
channel users.
|
||||
|
||||
**For flake users**, use the `deprecated` helper in `flake.nix`:
|
||||
|
||||
```nix
|
||||
old-module-name = deprecated "issue-number" "old-module-name" (import ./new/path);
|
||||
```
|
||||
|
||||
**For channel users**, add an assertion in the old module's `default.nix`:
|
||||
|
||||
```nix
|
||||
{ ... }:
|
||||
|
||||
{
|
||||
assertions = [
|
||||
{
|
||||
assertion = false;
|
||||
message = "Importing path/to/old/module (default.nix) directly is deprecated! See https://github.com/NixOS/nixos-hardware/blob/master/path/to/DEPRECATION.md for more details";
|
||||
}
|
||||
];
|
||||
}
|
||||
```
|
||||
|
||||
Include a markdown file explaining the migration path. See
|
||||
[asus/zephyrus/ga402x/ATTR-SET-DEPRECATION.md](asus/zephyrus/ga402x/ATTR-SET-DEPRECATION.md)
|
||||
for an example.
|
||||
|
||||
## Getting Help
|
||||
|
||||
For questions and discussions, join us in the
|
||||
[#nixos-hardware:nixos.org](https://matrix.to/#/#nixos-hardware:nixos.org)
|
||||
Matrix channel.
|
||||
|
||||
# For reviewers:
|
||||
|
||||
This repository has [mergify](https://mergify.com/) enabled for easier merging after a successfull build:
|
||||
Any nixpkgs committer can review and approve pull requests in this repository.
|
||||
|
||||
* `@mergify queue` will add the current pull request to the merge queue and merge when all tests succeed
|
||||
This repository uses GitHub merge queues for merging pull requests.
|
||||
|
||||
## Review checklist
|
||||
|
||||
1. **README.md entry**: Verify the contribution adds the device to the table in README.md
|
||||
2. **flake.nix entry**: Verify the profile is exposed in flake.nix
|
||||
3. **Common profiles**: Since testing on real hardware isn't always possible,
|
||||
check that the profile re-uses appropriate common profiles (e.g., cpu, gpu,
|
||||
laptop/pc, ssd/hdd modules)
|
||||
4. **Previous contributors**: For changes to existing profiles, consider
|
||||
requesting feedback from previous contributors who may have access to the
|
||||
hardware
|
||||
|
|
|
|||
Loading…
Add table
Add a link
Reference in a new issue