CONTRIBUTING.md: add info about updating templates, misc other changes
- a few small formatting/grammar changes/corrections - document cloning with https, github-cli - document using non-fork-master branch for changes - document not using web ui for commiting - add example commits for non-package changes - add xrevbump - reorder so testing build locally is before committing (more chronological) - update xtools URL - update example commits
This commit is contained in:
classabbyamp
classabbyamp
parent
8be7acf757
commit
f66f8adcde
@ -4,15 +4,16 @@ void-packages is the backbone of the Void Linux distribution. It contains all th
|
||||
|
||||
This document describes how you, as a contributor, can help with adding packages, correcting bugs and adding features to void-packages.
|
||||
|
||||
## Getting your packages into Void by yourself
|
||||
## Creating, updating, and modifying packages in Void by yourself
|
||||
|
||||
If you really want to get a package into Void Linux, we recommend you package it yourself.
|
||||
If you really want to get a new package or package update into Void Linux, we recommend you contribute it yourself.
|
||||
|
||||
We provide a [comprehensive Manual](./Manual.md) on how to create new packages.
|
||||
There's also a [manual for xbps-src](./README.md), which is used
|
||||
to build package files from templates.
|
||||
There's also a [manual for xbps-src](./README.md), which is used to build package files from templates.
|
||||
|
||||
For this guide, we assume you have basic knowledge about [git](http://git-scm.org), as well as a [GitHub Account](http://github.com).
|
||||
For this guide, we assume you have basic knowledge about [git](http://git-scm.org), as well as a [GitHub Account](http://github.com) with [SSH set up](https://docs.github.com/en/authentication/connecting-to-github-with-ssh).
|
||||
|
||||
You should also [set the email](https://docs.github.com/en/account-and-profile/setting-up-and-managing-your-personal-account-on-github/managing-email-preferences/setting-your-commit-email-address) on your GitHub account and in git so your commits are associated with your GitHub account properly.
|
||||
|
||||
To get started, [fork](https://help.github.com/articles/fork-a-repo) the void-linux `void-packages` git repository on GitHub and clone it:
|
||||
|
||||
@ -23,9 +24,24 @@ To keep your forked repository up to date, setup the `upstream` remote to pull i
|
||||
$ git remote add upstream https://github.com/void-linux/void-packages.git
|
||||
$ git pull --rebase upstream master
|
||||
|
||||
This can also be done with the `github-cli` tool:
|
||||
|
||||
$ gh repo fork void-linux/void-packages
|
||||
$ gh repo clone <user>/void-packages
|
||||
|
||||
This automatically sets up the `upstream` remote, so `git pull --rebase upstream master` can still be used to keep your fork up-to-date.
|
||||
|
||||
Using the GitHub web editor for making changes is strongly discouraged, because you will need to clone the repo anyways to edit and test your changes.
|
||||
|
||||
using the the `master` branch of your fork for contributing is also strongly discouraged.
|
||||
It can cause many issues with updating your pull request (also called a PR), and having multiple PRs open at once.
|
||||
To create a new branch:
|
||||
|
||||
$ git checkout master -b <a-descriptive-name>
|
||||
|
||||
### Creating a new template
|
||||
|
||||
You can use the helper tool `xnew`, from the [xtools](https://github.com/chneukirchen/xtools) package, to create new templates:
|
||||
You can use the helper tool `xnew`, from the [xtools](https://github.com/leahneukirchen/xtools) package, to create new templates:
|
||||
|
||||
$ xnew pkgname subpkg1 subpkg2 ...
|
||||
|
||||
@ -33,44 +49,58 @@ Templates must have the name `void-packages/srcpkgs/<pkgname>/template`, where `
|
||||
|
||||
For 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.
|
||||
|
||||
When you've finished working on the template file, please check it with `xlint` helper from the [xtools](https://github.com/chneukirchen/xtools) package:
|
||||
### Updating a template
|
||||
|
||||
At minimum, a template update will consist of changing `version` and `checksum`, if there was an upstream version change, and/or `revision`, if a template-specific change (e.g. patch, correction, etc.) is needed.
|
||||
Other changes to the template may be needed depending on what changes the upstream has made.
|
||||
|
||||
The checksum can be updated automatically with the `xgensum` helper from the [xtools](https://github.com/leahneukirchen/xtools) package:
|
||||
|
||||
$ xgensum -i <pkgname>
|
||||
|
||||
### Committing your changes
|
||||
|
||||
After making your changes, please check that the package builds successfully. From the top level directory of your local copy of the `void-packages` repository, run:
|
||||
|
||||
$ ./xbps-src pkg <pkgname>
|
||||
|
||||
Your package must build successfully for at least x86, but we recommend also trying a cross-build for armv6l* as well, e.g.:
|
||||
|
||||
$ ./xbps-src -a armv6l pkg <pkgname>
|
||||
|
||||
When building for `x86_64*` or `i686`, building with the `-Q` flag or with `XBPS_CHECK_PKGS=yes` set in `etc/conf` (to run the check phase) is strongly encouraged.
|
||||
Also, new packages and updates will not be accepted unless they have been runtime tested by installing and running the package.
|
||||
|
||||
When you've finished working on the template file, please check it with `xlint` helper from the [xtools](https://github.com/leahneukirchen/xtools) package:
|
||||
|
||||
$ xlint template
|
||||
|
||||
If `xlint` reports any issues, resolve them before committing.
|
||||
|
||||
### Committing your changes
|
||||
|
||||
Once 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:
|
||||
|
||||
* for new packages, use ```New package: <pkgname>-<version>``` ([example](https://github.com/void-linux/void-packages/commit/176d9655429188aac10cd229827f99b72982ab10)).
|
||||
* for new packages, use `New package: <pkgname>-<version>` ([example](https://github.com/void-linux/void-packages/commit/8ed8d41c40bf6a82cf006c7e207e05942c15bff8)).
|
||||
|
||||
* for package updates, use ```<pkgname>: update to <version>.``` ([example](https://github.com/void-linux/void-packages/commit/b6b82dcbd4aeea5fc37a32e4b6a8dd8bd980d5a3)).
|
||||
* for package updates, use `<pkgname>: update to <version>.` ([example](https://github.com/void-linux/void-packages/commit/c92203f1d6f33026ae89f3e4c1012fb6450bbac1)).
|
||||
|
||||
* for template modifications without a version change, use ```<pkgname>: <reason>``` ([example](https://github.com/void-linux/void-packages/commit/8b68d6bf1eb997cd5e7c095acd040e2c5379c91d)).
|
||||
* for template modifications without a version change, use `<pkgname>: <reason>` ([example](https://github.com/void-linux/void-packages/commit/ff39c912d412717d17232de9564f659b037e95b5)).
|
||||
|
||||
* for package removals, use ```<pkgname>: remove package``` ([example](https://github.com/void-linux/void-packages/commit/83784632d94deee5d038c8e1c4c1dffa922fca21)).
|
||||
* for package removals, use `<pkgname>: remove package` and include the removal reason in the commit body ([example](https://github.com/void-linux/void-packages/commit/4322f923bdf5d4e0eb36738d4f4717d72d0a0ca4)).
|
||||
|
||||
* for `common/shlibs` modifications, use `common/shlibs: <pkgname>` ([example](https://github.com/void-linux/void-packages/commit/613651c91811cb4fd2e1a6be701c87072d759a9f)).
|
||||
* for changes to any other file, use `<filename>: <reason>` ([example](https://github.com/void-linux/void-packages/commit/e00bea014c36a70d60acfa1758514b0c7cb0627d),
|
||||
[example](https://github.com/void-linux/void-packages/commit/93bf159ce10d8e474da5296e5bc98350d00c6c82), [example](https://github.com/void-linux/void-packages/commit/dc62938c67b66a7ff295eab541dc37b92fb9fb78), [example](https://github.com/void-linux/void-packages/commit/e52317e939d41090562cf8f8131a68772245bdde))
|
||||
|
||||
If 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)).
|
||||
If you want to describe your changes in more detail, explain in the commit body (separated from the first line with a blank line) ([example](https://github.com/void-linux/void-packages/commit/f1c45a502086ba1952f23ace9084a870ce437bc6)).
|
||||
|
||||
`xbump`, available in the [xtools](https://github.com/chneukirchen/xtools) package, can be used to commit a new or updated package:
|
||||
`xbump`, available in the [xtools](https://github.com/leahneukirchen/xtools) package, can be used to commit a new or updated package:
|
||||
|
||||
$ xbump <pkgname> <git commit options>
|
||||
|
||||
`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.
|
||||
`xrevbump`, also available in the [xtools](https://github.com/leahneukirchen/xtools) package, can be used to commit a template modification for a package:
|
||||
|
||||
After 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:
|
||||
$ xrevbump '<message>' <pkgnames...>
|
||||
|
||||
$ ./xbps-src pkg <pkgname>
|
||||
|
||||
Your package must build successfully for at least x86, but we recommend trying to build for armv* as well, e.g.:
|
||||
|
||||
$ ./xbps-src -a armv7l pkg <pkgname>
|
||||
|
||||
Runtime 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.
|
||||
New packages will not be accepted unless they have been runtime tested.
|
||||
`xbump` and `xrevbump` 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.
|
||||
|
||||
### Starting a pull request
|
||||
|
||||
@ -123,7 +153,7 @@ Once you have applied all requested changes, the reviewers will merge your reque
|
||||
If the pull request becomes inactive for some days, the reviewers may or may not warn you when they are about to close it.
|
||||
If it stays inactive further, it will be closed.
|
||||
|
||||
Please 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.
|
||||
Please abstain from temporarily closing a pull request while revising the templates. Instead, leave a comment on the PR describing what still needs work, [mark it as a draft](https://docs.github.com/en/pull-requests/collaborating-with-pull-requests/proposing-changes-to-your-work-with-pull-requests/changing-the-stage-of-a-pull-request#converting-a-pull-request-to-a-draft), 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.
|
||||
|
||||
#### Publishing the package
|
||||
|
||||
|
||||
Loading…
x
Reference in New Issue
Block a user