From 025d6a953114c4de946cb9df0bf7ed709b6f7e0e 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 --- CONTRIBUTING.md | 56 ++++++++++++++++++++++++++++++++++++++----------- 1 file changed, 44 insertions(+), 12 deletions(-) diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index 3f33aeb1d974..a8b5fcb93b0f 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -4,25 +4,45 @@ 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). +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: + # with SSH set up for GitHub (recommended) $ git clone git@github.com:/void-packages.git + # without SSH set up for GitHub + $ git clone https://github.com//void-packages.git To keep your forked repository up to date, setup the `upstream` remote to pull in new changes: $ 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. +It makes it harder to update your pull request later on and makes it harder to test the changes you have made. + +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: @@ -33,26 +53,38 @@ 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. +### 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/chneukirchen/xtools) package: + + $ xgensum -i + +### Committing your changes + 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 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: -``` ([example](https://github.com/void-linux/void-packages/commit/176d9655429188aac10cd229827f99b72982ab10)). +* for new packages, use `New package: -` ([example](https://github.com/void-linux/void-packages/commit/176d9655429188aac10cd229827f99b72982ab10)). -* for package updates, use ```: update to .``` ([example](https://github.com/void-linux/void-packages/commit/b6b82dcbd4aeea5fc37a32e4b6a8dd8bd980d5a3)). +* for package updates, use `: update to .` ([example](https://github.com/void-linux/void-packages/commit/b6b82dcbd4aeea5fc37a32e4b6a8dd8bd980d5a3)). -* for template modifications without a version change, use ```: ``` ([example](https://github.com/void-linux/void-packages/commit/8b68d6bf1eb997cd5e7c095acd040e2c5379c91d)). +* for template modifications without a version change, use `: ` ([example](https://github.com/void-linux/void-packages/commit/8b68d6bf1eb997cd5e7c095acd040e2c5379c91d)). -* for package removals, use ```: remove package``` ([example](https://github.com/void-linux/void-packages/commit/83784632d94deee5d038c8e1c4c1dffa922fca21)). +* for package removals, use `: remove package` and include the removal reason in the commit body ([example](https://github.com/void-linux/void-packages/commit/83784632d94deee5d038c8e1c4c1dffa922fca21)). * 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, add an empty line followed by those details ([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: @@ -69,8 +101,8 @@ Your package must build successfully for at least x86, but we recommend trying t $ ./xbps-src -a armv7l pkg -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. +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. ### Starting a pull request