[PR PATCH] Manual: some git info to CONTRIB, explain how to use different branch…

[PR PATCH] Manual: some git info to CONTRIB, explain how to use different branch…

[ericonr]

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

There is a new pull request by ericonr against master on the void-packages repository

https://github.com/ericonr/void-packages gitforce
https://github.com/void-linux/void-packages/pull/24450

Manual: some git info to CONTRIB, explain how to use different branch…
… in PR.

Supersedes #23788, which was closed accidentally and can't be reopened. Still missing some of the corrections.

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

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

From c99cb5bdef795a434460d087e1c9d912b099dadb Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?=C3=89rico=20Rolim?= <erico.erc@gmail.com>
Date: Thu, 23 Jul 2020 19:44:57 -0300
Subject: [PATCH] Manual: some git info to CONTRIB, explain how to use
 different branch in PR.

---
 CONTRIBUTING.md | 23 +++++++++++++++++++++--
 Manual.md       | 13 ++++---------
 2 files changed, 25 insertions(+), 11 deletions(-)

diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md
index a38751f55ec..d9316d0c5e2 100644
--- a/CONTRIBUTING.md
+++ b/CONTRIBUTING.md
@@ -16,6 +16,15 @@ For this guide, we assume you have basic knowledge about [git](http://git-scm.or
 
 Please note that we do not accept any packages containing non-release versions, such as specific git- or svn-revisions anymore.
 
+To get started, [fork](https://help.github.com/articles/fork-a-repo) the void-linux `void-packages` git repository on GitHub and clone it:
+
+    $ git clone git@github.com:<user>/void-packages.git
+
+To keep your forked repository up to date, setup the `upstream` remote to pull in new changes:
+
+    $ git remote add upstream git://github.com/void-linux/void-packages.git
+    $ git pull --rebase upstream master
+
 ### Creating a new template
 
 You can use the helper tool `xnew`, from the [xtools](https://github.com/chneukirchen/xtools) package, to create new templates:
@@ -48,6 +57,8 @@ Once you have built your template file or files, the commit message should have
 
 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)).
 
+Once you've made changes to your forked repository, you can [start a pull request](#starting-a-pull-request).
+
 Pull requests are automatically submitted for Continuous Integration (CI) testing to ensure packages build on various combinations of libc and architecture.
 Packages that take longer than 50 minutes to build (for example, Firefox or the Linux kernel) will fail CI and should include `[ci skip]` in the last line of the last commit message in the PR to avoid wasting CI builder time.
 Use your best judgment on build times based on your local building experience. If you skip CI when submitting a PR, please build and cross-build for a variety of architectures locally, with both glibc and musl, and note your local results in PR comments.
@@ -76,14 +87,14 @@ For further details, see the output of `./xbps-src -h`.
 
 ### Starting a pull request
 
-Once you have successfully built the package, you can start a pull request.
+Once you have successfully built the package, you can [create a pull request](https://docs.github.com/en/github/collaborating-with-issues-and-pull-requests/creating-a-pull-request).
 
 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 update `common/shlibs` and revbump all packages that are dependant.
 There should be a commit for each package revbump, and those commits should be part of the same pull request.
 
-When you make changes to your pull request, please *do not close and reopen your pull request*. Instead, just forcibly git push, overwriting any old commits. Closing and opening your pull requests repeatedly spams the Void maintainers.
+When you make changes to your pull request, please *do not close and reopen your pull request*. Instead, just [forcibly git push](#review), overwriting any old commits. Closing and opening your pull requests repeatedly spams the Void maintainers.
 
 #### Travis
 
@@ -101,6 +112,14 @@ We recommend having only a single commit for pull request, so if you need to mak
     $ git add <file>
     $ git commit --amend
     $ git push -f
+    
+A more powerful way of modifying commits than using `git commit --amend` is with [git-rebase](https://git-scm.com/docs/git-rebase#_interactive_mode), which allows you to join, reorder, change description of past commits and more.
+
+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
+    $ git push -f <fork> <attempt2>:<branch-of-pr>
 
 #### Closing the pull request
 
diff --git a/Manual.md b/Manual.md
index 854017adf80..cf06c183b30 100644
--- a/Manual.md
+++ b/Manual.md
@@ -2009,22 +2009,17 @@ otherwise the `debug` packages won't have debugging symbols.
 <a id="contributing"></a>
 ### Contributing via git
 
-Fork the voidlinux `void-packages` git repository on github and clone it:
+To get started, [fork](https://help.github.com/articles/fork-a-repo) the void-linux `void-packages` git repository on GitHub and clone it:
 
     $ git clone git@github.com:<user>/void-packages.git
 
-See [CONTRIBUTING.md](./CONTRIBUTING.md) for information on how to format your
-commits and other tips for contributing.
-
-Once you've made changes to your `forked` repository you can submit
-a github pull request; see https://help.github.com/articles/fork-a-repo for more information.
-
-To keep your forked repository always up to date, setup the `upstream` remote
-to pull in new changes:
+To keep your forked repository up to date, setup the `upstream` remote to pull in new changes:
 
     $ git remote add upstream git://github.com/void-linux/void-packages.git
     $ git pull --rebase upstream master
 
+See [CONTRIBUTING.md](./CONTRIBUTING.md) for more information on how to contribute to `void-packages`.
+
 <a id="help"></a>
 ## Help
 

Re: Manual: some git info to CONTRIB, explain how to use different branch…

[Chocimier]

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

New comment by Chocimier on void-packages repository

https://github.com/void-linux/void-packages/pull/24450#issuecomment-683897820

Comment:
Will merge if you address last comments from #23788.

Re: Manual: some git info to CONTRIB, explain how to use different branch…

[the-maldridge]

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

New comment by the-maldridge on void-packages repository

https://github.com/void-linux/void-packages/pull/24450#issuecomment-752355245

Comment:
@ericonr @Chocimier status?

Re: [PR PATCH] [Updated] Manual: some git info to CONTRIB, explain how to use different branch…

[Chocimier]

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

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

https://github.com/ericonr/void-packages gitforce
https://github.com/void-linux/void-packages/pull/24450

Manual: some git info to CONTRIB, explain how to use different branch…
… in PR.

Supersedes #23788, which was closed accidentally and can't be reopened. Still missing some of the corrections.

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

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

From 9c47419b1fe2e921e0375d302684dad6ed085e16 Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?=C3=89rico=20Rolim?= <erico.erc@gmail.com>
Date: Thu, 23 Jul 2020 19:44:57 -0300
Subject: [PATCH] Manual: some git info to CONTRIB, explain how to use
 different branch in PR.

---
 CONTRIBUTING.md | 23 +++++++++++++++++++++--
 Manual.md       | 13 ++++---------
 2 files changed, 25 insertions(+), 11 deletions(-)

diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md
index 6efdf4817e0..0b229261a65 100644
--- a/CONTRIBUTING.md
+++ b/CONTRIBUTING.md
@@ -16,6 +16,15 @@ For this guide, we assume you have basic knowledge about [git](http://git-scm.or
 
 Please note that we do not accept any packages containing non-release versions, such as specific git- or svn-revisions anymore.
 
+To get started, [fork](https://help.github.com/articles/fork-a-repo) the void-linux `void-packages` git repository on GitHub and clone it:
+
+    $ git clone git@github.com:<user>/void-packages.git
+
+To keep your forked repository up to date, setup the `upstream` remote to pull in new changes:
+
+    $ git remote add upstream git://github.com/void-linux/void-packages.git
+    $ git pull --rebase upstream master
+
 ### Creating a new template
 
 You can use the helper tool `xnew`, from the [xtools](https://github.com/chneukirchen/xtools) package, to create new templates:
@@ -48,6 +57,8 @@ Once you have built your template file or files, the commit message should have
 
 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)).
 
+Once you've made changes to your forked repository, you can [start a pull request](#starting-a-pull-request).
+
 Pull requests are automatically submitted for Continuous Integration (CI) testing to ensure packages build on various combinations of libc and architecture.
 Packages that take longer than 120 minutes or need more than 14G of storage to complete their build (for example, Firefox or the Linux kernel) will fail CI and should include `[ci skip]` in the PR title or body (the comment field when the PR is being opened) to avoid wasting CI builder time.
 Use your best judgment on build times based on your local building experience. If you skip CI when submitting a PR, please build and cross-build for a variety of architectures locally, with both glibc and musl, and note your local results in PR comments.
@@ -76,14 +87,14 @@ For further details, see the output of `./xbps-src -h`.
 
 ### Starting a pull request
 
-Once you have successfully built the package, you can start a pull request.
+Once you have successfully built the package, you can [create a pull request](https://docs.github.com/en/github/collaborating-with-issues-and-pull-requests/creating-a-pull-request).
 
 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 update `common/shlibs` and revbump all packages that are dependant.
 There should be a commit for each package revbump, and those commits should be part of the same pull request.
 
-When you make changes to your pull request, please *do not close and reopen your pull request*. Instead, just forcibly git push, overwriting any old commits. Closing and opening your pull requests repeatedly spams the Void maintainers.
+When you make changes to your pull request, please *do not close and reopen your pull request*. Instead, just [forcibly git push](#review), overwriting any old commits. Closing and opening your pull requests repeatedly spams the Void maintainers.
 
 #### Travis
 
@@ -101,6 +112,14 @@ We recommend having only a single commit for pull request, so if you need to mak
     $ git add <file>
     $ git commit --amend
     $ git push -f
+    
+A more powerful way of modifying commits than using `git commit --amend` is with [git-rebase](https://git-scm.com/docs/git-rebase#_interactive_mode), which allows you to join, reorder, change description of past commits and more.
+
+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
+    $ git push -f <fork> <attempt2>:<branch-of-pr>
 
 #### Closing the pull request
 
diff --git a/Manual.md b/Manual.md
index 922cbd30f45..d3a6ad7973c 100644
--- a/Manual.md
+++ b/Manual.md
@@ -2045,22 +2045,17 @@ otherwise the `debug` packages won't have debugging symbols.
 <a id="contributing"></a>
 ### Contributing via git
 
-Fork the voidlinux `void-packages` git repository on github and clone it:
+To get started, [fork](https://help.github.com/articles/fork-a-repo) the void-linux `void-packages` git repository on GitHub and clone it:
 
     $ git clone git@github.com:<user>/void-packages.git
 
-See [CONTRIBUTING.md](./CONTRIBUTING.md) for information on how to format your
-commits and other tips for contributing.
-
-Once you've made changes to your `forked` repository you can submit
-a github pull request; see https://help.github.com/articles/fork-a-repo for more information.
-
-To keep your forked repository always up to date, setup the `upstream` remote
-to pull in new changes:
+To keep your forked repository up to date, setup the `upstream` remote to pull in new changes:
 
     $ git remote add upstream git://github.com/void-linux/void-packages.git
     $ git pull --rebase upstream master
 
+See [CONTRIBUTING.md](./CONTRIBUTING.md) for more information on how to contribute to `void-packages`.
+
 <a id="help"></a>
 ## Help
 

Re: [PR PATCH] [Updated] Manual: some git info to CONTRIB, explain how to use different branch…

[Chocimier]

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

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

https://github.com/ericonr/void-packages gitforce
https://github.com/void-linux/void-packages/pull/24450

Manual: some git info to CONTRIB, explain how to use different branch…
… in PR.

Supersedes #23788, which was closed accidentally and can't be reopened. Still missing some of the corrections.

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

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

From 3bcd3a255c941c18adf1ff1ee623cfadd229d000 Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?=C3=89rico=20Rolim?= <erico.erc@gmail.com>
Date: Thu, 23 Jul 2020 19:44:57 -0300
Subject: [PATCH 1/2] Manual: some git info to CONTRIB, explain how to use
 different branch in PR.

---
 CONTRIBUTING.md | 21 +++++++++++++++++++--
 Manual.md       |  6 +++---
 2 files changed, 22 insertions(+), 5 deletions(-)

diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md
index 6efdf4817e0..985647ebe86 100644
--- a/CONTRIBUTING.md
+++ b/CONTRIBUTING.md
@@ -16,6 +16,15 @@ For this guide, we assume you have basic knowledge about [git](http://git-scm.or
 
 Please note that we do not accept any packages containing non-release versions, such as specific git- or svn-revisions anymore.
 
+To get started, [fork](https://help.github.com/articles/fork-a-repo) the void-linux `void-packages` git repository on GitHub and clone it:
+
+    $ git clone git@github.com:<user>/void-packages.git
+
+To keep your forked repository up to date, setup the `upstream` remote to pull in new changes:
+
+    $ git remote add upstream git://github.com/void-linux/void-packages.git
+    $ git pull --rebase upstream master
+
 ### Creating a new template
 
 You can use the helper tool `xnew`, from the [xtools](https://github.com/chneukirchen/xtools) package, to create new templates:
@@ -76,14 +85,14 @@ For further details, see the output of `./xbps-src -h`.
 
 ### Starting a pull request
 
-Once you have successfully built the package, you can start a pull request.
+Once you have successfully built the package, you can [create a pull request](https://docs.github.com/en/github/collaborating-with-issues-and-pull-requests/creating-a-pull-request).
 
 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 update `common/shlibs` and revbump all packages that are dependant.
 There should be a commit for each package revbump, and those commits should be part of the same pull request.
 
-When you make changes to your pull request, please *do not close and reopen your pull request*. Instead, just forcibly git push, overwriting any old commits. Closing and opening your pull requests repeatedly spams the Void maintainers.
+When you make changes to your pull request, please *do not close and reopen your pull request*. Instead, just [forcibly git push](#review), overwriting any old commits. Closing and opening your pull requests repeatedly spams the Void maintainers.
 
 #### Travis
 
@@ -102,6 +111,14 @@ We recommend having only a single commit for pull request, so if you need to mak
     $ git commit --amend
     $ git push -f
 
+A more powerful way of modifying commits than using `git commit --amend` is with [git-rebase](https://git-scm.com/docs/git-rebase#_interactive_mode), which allows you to join, reorder, change description of past commits and more.
+
+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
+    $ git push -f <fork> <attempt2>:<branch-of-pr>
+
 #### Closing the pull request
 
 Once you have applied all requested changes, the reviewers will merge your request.
diff --git a/Manual.md b/Manual.md
index 922cbd30f45..6481bb4ee50 100644
--- a/Manual.md
+++ b/Manual.md
@@ -2045,15 +2045,15 @@ otherwise the `debug` packages won't have debugging symbols.
 <a id="contributing"></a>
 ### Contributing via git
 
-Fork the voidlinux `void-packages` git repository on github and clone it:
+To get started, [fork](https://help.github.com/articles/fork-a-repo) the void-linux `void-packages` git repository on GitHub and clone it:
 
     $ git clone git@github.com:<user>/void-packages.git
 
 See [CONTRIBUTING.md](./CONTRIBUTING.md) for information on how to format your
 commits and other tips for contributing.
 
-Once you've made changes to your `forked` repository you can submit
-a github pull request; see https://help.github.com/articles/fork-a-repo for more information.
+Once you've made changes to your `forked` repository, submit
+a github pull request.
 
 To keep your forked repository always up to date, setup the `upstream` remote
 to pull in new changes:

From 68f3c591baf8f68967c98fead5bacbfc09020642 Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?Piotr=20W=C3=B3jcik?= <chocimier@tlen.pl>
Date: Wed, 30 Dec 2020 21:17:50 +0100
Subject: [PATCH 2/2] CONTRIBUTING.md: reorder description to match process

---
 CONTRIBUTING.md | 24 ++++++++++--------------
 1 file changed, 10 insertions(+), 14 deletions(-)

diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md
index 985647ebe86..334a0a1805c 100644
--- a/CONTRIBUTING.md
+++ b/CONTRIBUTING.md
@@ -57,21 +57,11 @@ Once you have built your template file or files, the commit message should have
 
 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)).
 
-Pull requests are automatically submitted for Continuous Integration (CI) testing to ensure packages build on various combinations of libc and architecture.
-Packages that take longer than 120 minutes or need more than 14G of storage to complete their build (for example, Firefox or the Linux kernel) will fail CI and should include `[ci skip]` in the PR title or body (the comment field when the PR is being opened) to avoid wasting CI builder time.
-Use your best judgment on build times based on your local building experience. If you skip CI when submitting a PR, please build and cross-build for a variety of architectures locally, with both glibc and musl, and note your local results in PR comments.
-Make sure to cover 64-bit and 32-bit architectures.
-
-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.
-
-For further information, please consult the [manual](https://github.com/void-linux/void-packages/blob/master/Manual.md).
-
 `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. 
+`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:
 
@@ -81,7 +71,8 @@ Your package must build successfully for at least x86, but we recommend trying t
 
     $ ./xbps-src -a armv7l pkg <pkgname>
 
-For further details, see the output of `./xbps-src -h`.
+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.
 
 ### Starting a pull request
 
@@ -96,8 +87,13 @@ 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 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.
+Pull requests are automatically submitted for Continuous Integration (CI) testing to ensure packages build on various combinations of libc and architecture.
+Packages that take longer than 120 minutes or need more than 14G of storage to complete their build (for example, Firefox or the Linux kernel) will fail CI and should include `[ci skip]` in the PR title or body (the comment field when the PR is being opened) to avoid wasting CI builder time.
+Use your best judgment on build times based on your local building experience. If you skip CI when submitting a PR, please build and cross-build for a variety of architectures locally, with both glibc and musl, and note your local results in PR comments.
+Make sure to cover 64-bit and 32-bit architectures.
+
+Continuous Integration will also check if the templates you have changed
+comply with the our guidelines. At the moment not all packages comply with the rules, so if you update a package, it may report errors about places you haven't touched. Please feel free to fix those errors too.
 
 #### Review
 

Re: Manual: some git info to CONTRIB, explain how to use different branch…

[Chocimier]

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

New comment by Chocimier on void-packages repository

https://github.com/void-linux/void-packages/pull/24450#issuecomment-752748539

Comment:
Restored pr mention in manual and reordered ci mentions. @ericonr, are you ok with that?

Re: Manual: some git info to CONTRIB, explain how to use different branch…

[ericonr]

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

New comment by ericonr on void-packages repository

https://github.com/void-linux/void-packages/pull/24450#issuecomment-752770668

Comment:
@Chocimier  Yup, feel free to merge. Thanks!

Re: [PR PATCH] [Merged]: Manual: some git info to CONTRIB, explain how to use different branch…

[the-maldridge]

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

There's a merged pull request on the void-packages repository

Manual: some git info to CONTRIB, explain how to use different branch…
https://github.com/void-linux/void-packages/pull/24450

Description:
… in PR.

Supersedes #23788, which was closed accidentally and can't be reopened. Still missing some of the corrections.