Skip to content

Latest commit

 

History

History
129 lines (87 loc) · 4.93 KB

CONTRIBUTING.md

File metadata and controls

129 lines (87 loc) · 4.93 KB
Raw

Contributing to NGIpkgs

This document is for people who want to contribute to NGIpkgs. This involves interacting with changes proposed as pull requests on GitHub to the NGIpkgs repository (which you're in right now).

This document assumes that you already know:

In addition, a GitHub account is required, which you can create on the GitHub sign-up page.

When to create pull requests to NGIpkgs

Packagers are encouraged to contribute Nix packages of NGI projects to Nixpkgs, instead of to this repository. However, there may be reasons speaking against that, including:

  • Making the package available more quickly.
  • The package is not a good candidate for Nixpkgs.
  • The package is a good candidate for Nixpkgs, but no one is willing to be a maintainer 😢.

In any case, it is encouraged to create a pull request to Nixpkgs, then to this repository, with a comment linking to the Nixpkgs pull request in the description and the Nix expressions.

Documentation style guide

When contributing documentation, do not split lines at arbitrary character lengths. Instead, write one sentence per line, as this makes it easier to review changes.

How to create pull requests to NGIpkgs

  1. Set up a local version of NGIpkgs. If you don't have write access to NGIpkgs, create a fork of the repository and clone it.

    git clone https://github.com/some-owner/ngipkgs.git
cd ngipkgs

  2. Create and switch to a new Git branch.

    git checkout -b some-branch

  3. To add a package, start by creating a package.nix file in the package directory pkgs/by-name/some-package, where some-package will be the package attribute name.

    mkdir -p pkgs/by-name/some-package
$EDITOR pkgs/by-name/some-package/package.nix

    Make sure to:

    • Test the package on x86_64-linux.

      git add pkgs/by-name/some-package
nix build .#some-package

    • Format the Nix expressions with nix fmt.

      nix fmt pkgs/by-name/some-package

    An existing example is libgnunetchat.

  4. To add a NixOS service module, start by creating a default.nix file in the directory projects/some-project where some-project is the project name corresponding to the last URL component in the NLnet project listing.

    mkdir -p projects/some-project
$EDITOR projects/some-project/default.nix

    Make sure to:

    • Add the module options in service.nix, and reference that file in default.nix. For example:

      nixos.modules = {
  services.some-project = ./service.nix;
};

      The module will then be accessible from nixosModules.services.some-project.

    • Add the module tests in test.nix, or under a test directory, and reference that file in default.nix. For example:

      nixos.tests.some-test = import ./test.nix args;

      The module tests will then be accessible from nixosTests.some-project.

    • Test the module on x86_64-linux.

      git add pkgs/by-name/some-package projects/some-project
nix build .#some-package.passthru.tests.some-test.driverInteractive
./result/bin/nixos-test-driver # Start a shell
# Once in the spawned shell, start a VM that will execute the tests
start_all() # Run the VM

    • Format the Nix expressions with nix fmt.

      nix fmt projects/some-project

    An existing example is Kbin.

  5. Commit the changes and push the commits.

    git commit -m "some-message"
git push --set-upstream origin some-branch

  6. Create a pull request to NGIpkgs. Respond to review comments, potential CI failures, and potential merge conflicts by updating the pull request. Always keep the pull request in a mergeable state.