From: classabbyamp <classabbyamp@users.noreply.github.com>
To: ml@inbox.vuxu.org
Subject: Re: [PR PATCH] [Updated] CONTRIBUTING.md: add info about updating templates, misc other changes
Date: Sat, 06 Aug 2022 05:11:57 +0200 [thread overview]
Message-ID: <20220806031157.uanE3hQushtMg9ahfk7hUh3l1Vzc776qPjFqRn49LI0@z> (raw)
In-Reply-To: <gh-mailinglist-notifications-41a7ca26-5023-4802-975b-f1789d68868e-void-packages-38491@inbox.vuxu.org>
[-- Attachment #1: Type: text/plain, Size: 615 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
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: 10882 bytes --]
From e0b212c9f45e9791ea3f1dab8a96651a8ae973a2 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
---
CONTRIBUTING.md | 84 ++++++++++++++++++++++++++++++++++---------------
1 file changed, 58 insertions(+), 26 deletions(-)
diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md
index 3f33aeb1d974..45a8f1a301e6 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,60 @@ 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 trying to build for armv* 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 armv7l pkg <pkgname>
-* for package removals, use ```<pkgname>: 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: <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/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 `<pkgname>: update to <version>.` ([example](https://github.com/void-linux/void-packages/commit/b6b82dcbd4aeea5fc37a32e4b6a8dd8bd980d5a3)).
- $ ./xbps-src pkg <pkgname>
+* for template modifications without a version change, use `<pkgname>: <reason>` ([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 `<pkgname>: 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 <pkgname>
+* 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))
+
+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>
+
+`xrevbump`, also available in the [xtools](https://github.com/leahneukirchen/xtools) package, can be used to commit a template modification for a package:
+
+ $ xrevbump '<message>' <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
@@ -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 <attempt2>
- $ # do changes anew
+ # do changes anew
$ git push -f <fork> <attempt2>:<branch-of-pr>
#### Closing the pull request
next prev parent reply other threads:[~2022-08-06 3:11 UTC|newest]
Thread overview: 36+ messages / expand[flat|nested] mbox.gz Atom feed top
2022-08-05 20:15 [PR PATCH] " classabbyamp
2022-08-05 20:27 ` [PR REVIEW] " paper42
2022-08-05 20:27 ` paper42
2022-08-05 20:27 ` paper42
2022-08-05 20:28 ` classabbyamp
2022-08-05 20:31 ` paper42
2022-08-05 20:32 ` paper42
2022-08-05 20:33 ` paper42
2022-08-05 20:40 ` [PR PATCH] [Updated] " classabbyamp
2022-08-05 20:41 ` classabbyamp
2022-08-05 21:10 ` [PR REVIEW] " tranzystorek-io
2022-08-05 21:21 ` [PR PATCH] [Updated] " classabbyamp
2022-08-05 22:01 ` [PR REVIEW] " Chocimier
2022-08-05 22:01 ` Chocimier
2022-08-05 22:01 ` Chocimier
2022-08-05 22:01 ` Chocimier
2022-08-06 3:11 ` classabbyamp [this message]
2022-08-06 3:33 ` [PR PATCH] [Updated] " classabbyamp
2022-08-06 3:38 ` classabbyamp
2022-08-06 6:17 ` [PR REVIEW] " tranzystorek-io
2022-08-06 6:27 ` classabbyamp
2022-08-06 6:32 ` tranzystorek-io
2022-08-06 6:37 ` classabbyamp
2022-08-06 6:37 ` classabbyamp
2022-08-06 6:48 ` tranzystorek-io
2022-08-06 7:00 ` Chocimier
2022-08-06 14:25 ` [PR PATCH] [Updated] " classabbyamp
2022-08-06 14:28 ` [PR REVIEW] " classabbyamp
2022-08-06 15:58 ` paper42
2022-08-06 15:58 ` paper42
2022-08-06 15:58 ` paper42
2022-08-06 15:58 ` paper42
2022-08-06 16:45 ` [PR PATCH] [Updated] " classabbyamp
2022-08-10 19:45 ` classabbyamp
2022-08-12 16:48 ` classabbyamp
2022-08-12 16:48 ` [PR PATCH] [Merged]: " classabbyamp
Reply instructions:
You may reply publicly to this message via plain-text email
using any one of the following methods:
* Save the following mbox file, import it into your mail client,
and reply-to-all from there: mbox
Avoid top-posting and favor interleaved quoting:
https://en.wikipedia.org/wiki/Posting_style#Interleaved_style
* Reply using the --to, --cc, and --in-reply-to
switches of git-send-email(1):
git send-email \
--in-reply-to=20220806031157.uanE3hQushtMg9ahfk7hUh3l1Vzc776qPjFqRn49LI0@z \
--to=classabbyamp@users.noreply.github.com \
--cc=ml@inbox.vuxu.org \
/path/to/YOUR_REPLY
https://kernel.org/pub/software/scm/git/docs/git-send-email.html
* If your mail client supports setting the In-Reply-To header
via mailto: links, try the mailto: link
Be sure your reply has a Subject: header at the top and a blank line
before the message body.
This is a public inbox, see mirroring instructions
for how to clone and mirror all data and code used for this inbox;
as well as URLs for NNTP newsgroup(s).