void-packages

Void Source Packages
git clone git://ezup.dev/void-packages.git
Log | Files | Refs | README | LICENSE

CONTRIBUTING.md (8398B)


      1# Contributing to void-packages
      2
      3void-packages is the backbone of the Void Linux distribution. It contains all the definitions to build packages from source.
      4
      5This document describes how you, as a contributor, can help with adding packages, correcting bugs and adding features to void-packages.
      6
      7## Getting your packages into Void by yourself
      8
      9If you really want to get a package into Void Linux, we recommend you package it yourself.
     10
     11We provide a [comprehensive Manual](./Manual.md) on how to create new packages.
     12There's also a [manual for xbps-src](./README.md), which is used
     13to build package files from templates.
     14
     15For this guide, we assume you have basic knowledge about [git](http://git-scm.org), as well as a [GitHub Account](http://github.com).
     16
     17To get started, [fork](https://help.github.com/articles/fork-a-repo) the void-linux `void-packages` git repository on GitHub and clone it:
     18
     19    $ git clone git@github.com:<user>/void-packages.git
     20
     21To keep your forked repository up to date, setup the `upstream` remote to pull in new changes:
     22
     23    $ git remote add upstream git://github.com/void-linux/void-packages.git
     24    $ git pull --rebase upstream master
     25
     26### Creating a new template
     27
     28You can use the helper tool `xnew`, from the [xtools](https://github.com/chneukirchen/xtools) package, to create new templates:
     29
     30    $ xnew pkgname subpkg1 subpkg2 ...
     31
     32Templates must have the name `void-packages/srcpkgs/<pkgname>/template`, where `pkgname` is the same as the `pkgname` variable in the template.
     33
     34For deeper insights on the contents of template files, please read the [manual](./Manual.md), and be sure to browse the existing template files in the `srcpkgs` directory of this repository for concrete examples.
     35
     36When you've finished working on the template file, please check it with `xlint` helper from the [xtools](https://github.com/chneukirchen/xtools) package:
     37
     38    $ xlint template
     39
     40If `xlint` reports any issues, resolve them before committing.
     41
     42### Committing your changes
     43
     44Once you have made and verified your changes to the package template and/or other files, make one commit per package (including all changes to its sub-packages). Each commit message should have one of the following formats:
     45
     46* for new packages, use ```New package: <pkgname>-<version>``` ([example](https://github.com/void-linux/void-packages/commit/176d9655429188aac10cd229827f99b72982ab10)).
     47
     48* for package updates, use ```<pkgname>: update to <version>.``` ([example](https://github.com/void-linux/void-packages/commit/b6b82dcbd4aeea5fc37a32e4b6a8dd8bd980d5a3)).
     49
     50* for template modifications without a version change, use ```<pkgname>: <reason>``` ([example](https://github.com/void-linux/void-packages/commit/8b68d6bf1eb997cd5e7c095acd040e2c5379c91d)).
     51
     52* for package removals, use ```<pkgname>: remove package``` ([example](https://github.com/void-linux/void-packages/commit/83784632d94deee5d038c8e1c4c1dffa922fca21)).
     53
     54* for `common/shlibs` modifications, use `common/shlibs: <pkgname>` ([example](https://github.com/void-linux/void-packages/commit/613651c91811cb4fd2e1a6be701c87072d759a9f)).
     55
     56If you want to describe your changes in more detail, add an empty line followed by those details ([example](https://github.com/void-linux/void-packages/commit/f1c45a502086ba1952f23ace9084a870ce437bc6)).
     57
     58`xbump`, available in the [xtools](https://github.com/chneukirchen/xtools) package, can be used to commit a new or updated package:
     59
     60    $ xbump <pkgname> <git commit options>
     61
     62`xbump` will use `git commit` to commit the changes with the appropriate commit message. For more fine-grained control over the commit, specific options can be passed to `git commit` by adding them after the package name.
     63
     64After committing your changes, please check that the package builds successfully. From the top level directory of your local copy of the `void-packages` repository, run:
     65
     66    $ ./xbps-src pkg <pkgname>
     67
     68Your package must build successfully for at least x86, but we recommend trying to build for armv* as well, e.g.:
     69
     70    $ ./xbps-src -a armv7l pkg <pkgname>
     71
     72Runtime testing of packages and building with the `-Q` flag or with `XBPS_CHECK_PKGS=yes` set in the environment or `etc/conf` are strongly encouraged.
     73New packages will not be accepted unless they have been runtime tested.
     74
     75### Starting a pull request
     76
     77Once you have successfully built the package, you can [create a pull request](https://docs.github.com/en/github/collaborating-with-issues-and-pull-requests/creating-a-pull-request). Pull requests are also known as PRs.
     78
     79Most pull requests should only contain a single package and dependencies which are not part of void-packages yet.
     80
     81If you make updates to packages containing a soname bump, you also need to update `common/shlibs` and revbump all packages that are dependant.
     82There should be a commit for each package revbump, and those commits should be part of the same pull request.
     83
     84When you make changes to your pull request, please *do not close and reopen your pull request*. Instead, just [forcibly git push](#review), overwriting any old commits. Closing and opening your pull requests repeatedly spams the Void maintainers.
     85
     86#### Continuous Integration
     87
     88Pull requests are automatically submitted for Continuous Integration (CI) testing to ensure packages build and pass their tests (on native builds) on various combinations of C library and architecture.
     89Packages that take longer than 120 minutes or need more than 14G of storage to complete their build (for example, Firefox or the Linux kernel) will fail CI and should include `[ci skip]` in the PR title or body (the comment field when the PR is being opened) to avoid wasting CI builder time.
     90Use your best judgment on build times based on your local building experience. If you skip CI when submitting a PR, please build and cross-build for a variety of architectures locally, with both glibc and musl, and note your local results in PR comments.
     91Make sure to cover 64-bit and 32-bit architectures.
     92
     93If you notice a failure in CI that didn't happen locally, that is likely because you didn't run tests locally.
     94Use `./xbps-src -Q pkg <package>` to do so.
     95Some tests won't work in the CI environment or at all, and their templates should encode this information using the `make_check` variable.
     96
     97Continuous Integration will also check if the templates you have changed
     98comply with the our guidelines. At the moment not all packages comply with the rules, so if you update a package, it may report errors about places you haven't touched. Please feel free to fix those errors too.
     99
    100#### Review
    101
    102It's possible (and common) that a pull request will contain mistakes or reviewers will ask for additional tweaks.
    103Reviewers will comment on your pull request and point out which changes are needed before the pull request can be merged.
    104
    105Most PRs will have a single commit, as seen [above](#committing-your-changes), so if you need to make changes to the commit and already have a pull request open, you can use the following commands:
    106
    107    $ git add <file>
    108    $ git commit --amend
    109    $ git push -f
    110
    111A more powerful way of modifying commits than using `git commit --amend` is with [git-rebase](https://git-scm.com/docs/git-rebase#_interactive_mode), which allows you to join, reorder, change description of past commits and more.
    112
    113Alternatively, if there are issues with your git history, you can make another branch and push it to the existing PR:
    114
    115    $ git checkout master -b <attempt2>
    116    $ # do changes anew
    117    $ git push -f <fork> <attempt2>:<branch-of-pr>
    118
    119#### Closing the pull request
    120
    121Once you have applied all requested changes, the reviewers will merge your request.
    122
    123If the pull request becomes inactive for some days, the reviewers may or may not warn you when they are about to close it.
    124If it stays inactive further, it will be closed.
    125
    126Please abstain from temporarily closing a pull request while revising the templates. Instead, leave a comment on the PR describing what still needs work, or add "[WIP]" to the PR title. Only close your pull request if you're sure you don't want your changes to be included.
    127
    128#### Publishing the package
    129
    130Once the reviewers have merged the pull request, our [build server](http://build.voidlinux.org) is automatically triggered and builds
    131all packages in the pull request for all supported platforms. Upon completion, the packages are available to all Void Linux users.