aboutsummaryrefslogtreecommitdiff
path: root/CONTRIBUTING.md
diff options
context:
space:
mode:
authorAlexis <flexibeast@gmail.com>2019-11-13 11:38:01 +0000
committerJuan RP <xtraeme@gmail.com>2020-03-03 10:57:20 +0000
commit103da6edebd39e4d2b08f12ebd1259744e3be353 (patch)
tree202b940903de3508b22e3a9054be921833b75f1d /CONTRIBUTING.md
parent48b866b82a1a9a081e05f624f88d7a509d89f419 (diff)
downloadvoid-packages-103da6edebd39e4d2b08f12ebd1259744e3be353.tar
void-packages-103da6edebd39e4d2b08f12ebd1259744e3be353.tar.gz
void-packages-103da6edebd39e4d2b08f12ebd1259744e3be353.tar.bz2
void-packages-103da6edebd39e4d2b08f12ebd1259744e3be353.tar.lz
void-packages-103da6edebd39e4d2b08f12ebd1259744e3be353.tar.xz
void-packages-103da6edebd39e4d2b08f12ebd1259744e3be353.tar.zst
void-packages-103da6edebd39e4d2b08f12ebd1259744e3be353.zip
Multiple changes to CONTRIBUTING.md.
* Describe using `xbps-src pkg` to check that a package builds. * Move mention of `xlint` to the 'Creating ...' section. * Remove reference to GitHub reporting new PRs on IRC. * Fix grammar and typos. * Improve readability.
Diffstat (limited to 'CONTRIBUTING.md')
-rw-r--r--CONTRIBUTING.md85
1 files changed, 44 insertions, 41 deletions
diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md
index 76e4b6c1ff4..0490b5f11c2 100644
--- a/CONTRIBUTING.md
+++ b/CONTRIBUTING.md
@@ -1,62 +1,73 @@
# Contributing to void-packages
-void-packages is the backbone of the Void Linux distribution. It contains all definitions how packages are built from source.
+void-packages is the backbone of the Void Linux distribution. It contains all the definitions to build packages from source.
-This document describes how you as a contributor can help adding packages, correcting bugs and adding features to void-packages.
+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
-If you really want to get a package into Void Linux we recommend you to package it yourself.
+If you really want to get a package into Void Linux, we recommend you package it yourself.
+
We provide a [comprehensive Manual](https://github.com/void-linux/void-packages/blob/master/Manual.md)
-on how you can create new packages. Also there's a
-[manual about xbps-src](https://github.com/void-linux/void-packages/blob/master/README.md) which is used
+on how to create new packages. There's also a
+[manual for xbps-src](https://github.com/void-linux/void-packages/blob/master/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) and 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).
-Please note that we do not accept any packages containing non-release versions such
-as specific git- or svn-revisions anymore.
+Please note that we do not accept any packages containing non-release versions, such as specific git- or svn-revisions anymore.
### Creating a new template
-templates must be placed in `void-packages/srcpkgs/<pkgname>/template` where `pkgname` is the same as the pkgname variable in the template.
+You can use the helper tool `xnew`, from the [xtools](https://github.com/chneukirchen/xtools) package, to create new templates:
+
+ $ xnew pkgname subpkg1 subpkg2 ...
-For deeper insights on the contents of template files consider reading the [manual](https://github.com/void-linux/void-packages/blob/master/Manual.md), and be sure to browse the existing template files in the `srcpkgs` directory of this repository for concrete examples.
+Templates must have the name `void-packages/srcpkgs/<pkgname>/template`, where `pkgname` is the same as the `pkgname` variable in the template.
-There's a helper tool for creating new packages in the [xtools](https://github.com/leahneukirchen/xtools) package:
+For deeper insights on the contents of template files, please read the [manual](https://github.com/void-linux/void-packages/blob/master/Manual.md), and be sure to browse the existing template files in the `srcpkgs` directory of this repository for concrete examples.
- $ xnew pkgname subpkg1 subpkg2 ...
+When you've finished working on the template file, please check it with `xlint` helper from the [xtools](https://github.com/chneukirchen/xtools) package:
+ $ xlint template
+
+If `xlint` reports any issues, resolve them before committing.
### Committing your changes
-Once you have built your template files there are certain rules on how the commit should be named.
+Once you have built your template file or files, the commit message should have one of the following forms:
-* Use the following for newly added packages: ```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/176d9655429188aac10cd229827f99b72982ab10)).
-* Use the following if you update a package: ```<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/b6b82dcbd4aeea5fc37a32e4b6a8dd8bd980d5a3)).
-* If you changed something on the template 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/8b68d6bf1eb997cd5e7c095acd040e2c5379c91d)).
-If you want to describe your changes in more detail, make an empty line and add the description afterwards.
-[Example](https://github.com/void-linux/void-packages/commit/f1c45a502086ba1952f23ace9084a870ce437bc6)
+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)).
-This is also described in the [manual](https://github.com/void-linux/void-packages/blob/master/Manual.md) in deeper detail.
+For further information, please consult the [manual](https://github.com/void-linux/void-packages/blob/master/Manual.md).
-There's a helper tool for committing packages in the [xtools](https://github.com/leahneukirchen/xtools) package, which can be used when adding or updating a package:
+`xbump`, available in the [xtools](https://github.com/chneukirchen/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.
+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:
+
+ $ ./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>
+
+For further details, see the output of `./xbps-src -h`.
+
### Starting a pull request
-Once you successfully build the package at least on x86 (building it on armv* is recommended too) you can start a pull request.
+Once you have successfully built the package, you can start a pull request.
-Most pull request should only contain a single package and its dependencies which are not part of void-packages yet.
+Most pull requests should only contain a single package and dependencies which are not part of void-packages yet.
If you make updates to packages containing a soname bump you also need to revbump all packages that are dependant. Those
packages should also be part of the same pull request.
@@ -66,38 +77,30 @@ When you make changes to your pull request, please *do not close and reopen your
#### Travis
Once you have started a pull request, you will get instant feedback from Travis. It will check if the templates you have changed
-comply with the our guidelines. At the moment not all packages comply to the rules, so if you update a package, it may happen, that Travis
-reports errors on places you haven't touched. So feel free to fix those errors too.
-
-You are encouraged to check your templates beforehand using the helper from the [xtools](https://github.com/leahneukirchen/xtools) package:
-
- $ xlint template
+comply with the our guidelines. At the moment not all packages comply with the rules, so if you update a package, it may happen that Travis reports errors about places you haven't touched. Please feel free to fix those errors too.
#### Review
-GitHub reports new pull request at our IRC-Channel, so the reviewers will be instantly informed. Most of the time
-your pull request will contain mistakes. It's nothing bad, it just happens.
+Most of the time your pull request will contain mistakes. It's nothing bad, it just happens.
-The reviewers will comment your pull request and point out which changes are needed before the template can be included.
+Reviewers will comment on your pull request and point out which changes are needed before the template can be included.
We recommend having only a single commit for pull request, so if you need to make changes in commits but already have a pull request, use the following commands:
-
$ git add <file>
$ git commit --amend
$ git push -f
#### Closing the pull request
-Once you have applied all comments, the reviewers will merge your request.
+Once you have applied all requested changes, the reviewers will merge your request.
-If the pull request gets 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'll be closed.
+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 temporary closing a pull request while revising the templates. 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, 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
Once the reviewers have merged the pull request, our [build server](http://build.voidlinux.org) is automatically triggered and builds
-all packages from this pull request for all supported platforms. Once it is finished, the packages are available to all Void Linux users.
+all packages in the pull request for all supported platforms. Upon completion, the packages are available to all Void Linux users.