Re: [PR PATCH] [Updated] CONTRIBUTING.md: add info about updating templates, misc other changes

[classabbyamp <classabbyamp@users.noreply.github.com>]

[-- Attachment #1: Type: text/plain, Size: 732 bytes --]

There is an updated pull request by classabbyamp against master on the void-packages repository

https://github.com/classabbyamp/void-packages contrib-updating
https://github.com/void-linux/void-packages/pull/38491

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

A patch file from https://github.com/void-linux/void-packages/pull/38491.patch is attached

[-- Warning: decoded text below may be mangled, UTF-8 assumed --]
[-- Attachment #2: github-pr-contrib-updating-38491.patch --]
[-- Type: text/x-diff, Size: 11557 bytes --]

From 752b408b72ff32aa9e467087ac4bc9a8cf3a64d0 Mon Sep 17 00:00:00 2001
From: classabbyamp <void@placeviolette.net>
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
- update example commits
---
 CONTRIBUTING.md | 82 +++++++++++++++++++++++++++++++++----------------
 1 file changed, 56 insertions(+), 26 deletions(-)

diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md
index 3f33aeb1d974..b21b9acdc5eb 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 <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
 
-    $ 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 <pkgname>
 
 ### 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: <pkgname>-<version>``` ([example](https://github.com/void-linux/void-packages/commit/176d9655429188aac10cd229827f99b72982ab10)).
+    $ ./xbps-src pkg <pkgname>
 
-* for package updates, use ```<pkgname>: update to <version>.``` ([example](https://github.com/void-linux/void-packages/commit/b6b82dcbd4aeea5fc37a32e4b6a8dd8bd980d5a3)).
+Your package must build successfully for at least x86, but we recommend also trying a cross-build for armv6l* as well, e.g.:
 
-* for template modifications without a version change, use ```<pkgname>: <reason>``` ([example](https://github.com/void-linux/void-packages/commit/8b68d6bf1eb997cd5e7c095acd040e2c5379c91d)).
+    $ ./xbps-src -a armv6l pkg <pkgname>
 
-* for package removals, use ```<pkgname>: remove package``` ([example](https://github.com/void-linux/void-packages/commit/83784632d94deee5d038c8e1c4c1dffa922fca21)).
+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.
 
-* for `common/shlibs` modifications, use `common/shlibs: <pkgname>` ([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 <pkgname> <git commit options>
+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: <pkgname>-<version>` ([example](https://github.com/void-linux/void-packages/commit/8ed8d41c40bf6a82cf006c7e207e05942c15bff8)).
 
-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 `<pkgname>: update to <version>.` ([example](https://github.com/void-linux/void-packages/commit/c92203f1d6f33026ae89f3e4c1012fb6450bbac1)).
 
-    $ ./xbps-src pkg <pkgname>
+* 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` and include the removal reason in the commit body ([example](https://github.com/void-linux/void-packages/commit/4322f923bdf5d4e0eb36738d4f4717d72d0a0ca4)).
+
+* 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, 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 <pkgname> <git commit options>
 
-Your package must build successfully for at least x86, but we recommend trying to build for armv* as well, e.g.:
+`xrevbump`, also available in the [xtools](https://github.com/leahneukirchen/xtools) package, can be used to commit a template modification for a package:
 
-    $ ./xbps-src -a armv7l pkg <pkgname>
+    $ xrevbump '<message>' <pkgnames...>
 
-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