From b9da74b419026d47d5b1277e6ac7bf3c1f9660ca Mon Sep 17 00:00:00 2001 From: classabbyamp Date: Fri, 5 Aug 2022 16:08:58 -0400 Subject: [PATCH] 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 --- CONTRIBUTING.md | 86 +++++++++++++++++++++++++++++++++---------------- 1 file changed, 59 insertions(+), 27 deletions(-) diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index 3f33aeb1d974..2aa74c48578c 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -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 /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 + ### 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,60 @@ Templates must have the name `void-packages/srcpkgs//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 - $ xlint 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. -If `xlint` reports any issues, resolve them before committing. +The checksum can be updated automatically with the `xgensum` helper from the [xtools](https://github.com/leahneukirchen/xtools) package: + + $ xgensum -i ### 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: +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: -* for new packages, use ```New package: -``` ([example](https://github.com/void-linux/void-packages/commit/176d9655429188aac10cd229827f99b72982ab10)). + $ ./xbps-src pkg -* for package updates, use ```: update to .``` ([example](https://github.com/void-linux/void-packages/commit/b6b82dcbd4aeea5fc37a32e4b6a8dd8bd980d5a3)). +Your package must build successfully for at least x86, but we recommend trying to build for armv* as well, e.g.: -* for template modifications without a version change, use ```: ``` ([example](https://github.com/void-linux/void-packages/commit/8b68d6bf1eb997cd5e7c095acd040e2c5379c91d)). + $ ./xbps-src -a armv7l pkg -* for package removals, use ```: remove package``` ([example](https://github.com/void-linux/void-packages/commit/83784632d94deee5d038c8e1c4c1dffa922fca21)). +When building for a native architecture (`x86_64*`, `i686`), building with the `-Q` flag or with `XBPS_CHECK_PKGS=yes` set in `etc/conf` (to run the check phase) is strongly encouraged. +New packages and updates will not be accepted unless they have been runtime tested. -* for `common/shlibs` modifications, use `common/shlibs: ` ([example](https://github.com/void-linux/void-packages/commit/613651c91811cb4fd2e1a6be701c87072d759a9f)). +When you've finished working on the template file, please check it with `xlint` helper from the [xtools](https://github.com/leahneukirchen/xtools) package: -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)). + $ xlint template -`xbump`, available in the [xtools](https://github.com/chneukirchen/xtools) package, can be used to commit a new or updated package: +If `xlint` reports any issues, resolve them before committing. - $ xbump +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: -`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. +* for new packages, use `New package: -` ([example](https://github.com/void-linux/void-packages/commit/176d9655429188aac10cd229827f99b72982ab10)). -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: +* for package updates, use `: update to .` ([example](https://github.com/void-linux/void-packages/commit/b6b82dcbd4aeea5fc37a32e4b6a8dd8bd980d5a3)). - $ ./xbps-src pkg +* for template modifications without a version change, use `: ` ([example](https://github.com/void-linux/void-packages/commit/8b68d6bf1eb997cd5e7c095acd040e2c5379c91d)). -Your package must build successfully for at least x86, but we recommend trying to build for armv* as well, e.g.: +* for package removals, use `: remove package` and include the removal reason in the commit body ([example](https://github.com/void-linux/void-packages/commit/3837665503241835bddb73be14d269cf9dbc6020)). - $ ./xbps-src -a armv7l pkg +* for `common/shlibs` modifications, use `common/shlibs: ` ([example](https://github.com/void-linux/void-packages/commit/613651c91811cb4fd2e1a6be701c87072d759a9f)). + +* for changes to any other file, use `: ` ([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)) + +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/leahneukirchen/xtools) package, can be used to commit a new or updated package: + + $ xbump + +`xrevbump`, also available in the [xtools](https://github.com/leahneukirchen/xtools) package, can be used to commit a template modification for a package: + + $ xrevbump '' -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 @@ -113,7 +145,7 @@ A more powerful way of modifying commits than using `git commit --amend` is with Alternatively, if there are issues with your git history, you can make another branch and push it to the existing PR: $ git checkout master -b - $ # do changes anew + # do changes anew $ git push -f : #### Closing the pull request @@ -123,7 +155,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