[PATCH] doc: Run guix refresh -l to find out about dependent packages.

[PATCH] doc: Run guix refresh -l to find out about dependent packages.

[ng0]

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

This adds an item about guix refresh to the contributing section of the
docs.
-- 
♥Ⓐ  ng0
Current Keys: https://we.make.ritual.n0.is/ng0.txt
For non-prism friendly talk find me on http://www.psyced.org

[-- Warning: decoded text below may be mangled, UTF-8 assumed --]
[-- Attachment #2: 0001-doc-Run-guix-refresh-l-to-find-out-about-dependent-p.patch --]
[-- Type: text/x-patch, Size: 1550 bytes --]

From 5fead8acf58b4ce000c60381a02db688561dbf05 Mon Sep 17 00:00:00 2001
From: ng0 <ng0@we.make.ritual.n0.is>
Date: Thu, 28 Jul 2016 11:06:32 +0000
Subject: [PATCH] doc: Run guix refresh -l to find out about dependent
 packages.

* doc/contributing.texi (Submitting Patches): Includes an item to
explain that core-updates and core-updates-next exist and that your
change will be applied on them if it affects too many dependent
packages, example: libgcrypt.
---
 doc/contributing.texi | 15 +++++++++++++++
 1 file changed, 15 insertions(+)

diff --git a/doc/contributing.texi b/doc/contributing.texi
index c0755bb..cfad190 100644
--- a/doc/contributing.texi
+++ b/doc/contributing.texi
@@ -328,6 +328,21 @@ extensions---or to the operating system kernel---e.g., reliance on
 @code{uname} or @file{/proc} files.
 
 @item
+Run @command{guix refresh --list-dependent} (@pxref{Invoking guix refresh})
+to find out how many packages would rebuild based on your patch.
+When your patch touches important or a big number of packages, it is
+prefered to be applied on the git branch core-updates or core-updates-next.
+
+@example
+guix refresh -l libgcrypt
+Building the following 822 packages would ensure 2221 dependent packages
+are rebuilt:
+@end example
+
+This is a good example for a number which indicates that a change to
+libgcrypt would not simply be applied on master.
+
+@item
 When writing documentation, please use gender-neutral wording when
 referring to people, such as
 @uref{https://en.wikipedia.org/wiki/Singular_they, singular
-- 
2.9.2

Re: [PATCH] doc: Run guix refresh -l to find out about dependent packages.

[Vincent Legoll]

Maybe, it'd better to get a real native English speaker review, but
until he comes, here are my comments:

"how many packages would rebuild"
"how many packages have to be rebuilt"

"for a number which indicates that a change to"
"for why your change to"

IANANES...

-- 
Vincent Legoll

Re: [PATCH] doc: Run guix refresh -l to find out about dependent packages.

[Ludovic Courtès]

ng0 <ng0@we.make.ritual.n0.is> skribis:

> --- a/doc/contributing.texi
> +++ b/doc/contributing.texi
> @@ -328,6 +328,21 @@ extensions---or to the operating system kernel---e.g., reliance on
>  @code{uname} or @file{/proc} files.
>  
>  @item
> +Run @command{guix refresh --list-dependent} (@pxref{Invoking guix refresh})
> +to find out how many packages would rebuild based on your patch.
> +When your patch touches important or a big number of packages, it is
> +prefered to be applied on the git branch core-updates or core-updates-next.
> +
> +@example
> +guix refresh -l libgcrypt
> +Building the following 822 packages would ensure 2221 dependent packages
> +are rebuilt:
> +@end example
> +
> +This is a good example for a number which indicates that a change to
> +libgcrypt would not simply be applied on master.

‘guix refresh -l’ is already mentioned in that section:

  https://www.gnu.org/software/guix/manual/html_node/Submitting-Patches.html

The specific branch names are not mentioned, but that’s also because
this process is still in flux.  “core-updates” initially meant “updates
to the core”, where “core” designates GCC, libc, Binutils, and a few
other packages that make up the implicit inputs of gnu-build-system.

Python, libgcrypt, and similar packages are not “core” packages,
strictly speaking.  Ideally, we’d run ‘python-updates’,
‘libgcrypt-updates’, etc. branches, but whether we do this depends on
our build farm capacity and on its current load.

In short, I think it’s best not too give too many details about a
process that’s not set in stone.  :-)

Thoughts?

Ludo’.

Re: [PATCH] doc: Run guix refresh -l to find out about dependent packages.

[Ludovic Courtès]

ng0 <ng0@we.make.ritual.n0.is> skribis:

> * doc/contributing.texi (Submitting Patches): Includes an item to
> explain that core-updates and core-updates-next exist and that your
> change will be applied on them if it affects too many dependent
> packages, example: libgcrypt.

In the end I added something a bit more general in commit
189b1543cbc2db50e6dd309e84bce4eb503f0493.

Ludo’.

Re: [PATCH] doc: Run guix refresh -l to find out about dependent packages.

[ng0]

Vincent Legoll <vincent.legoll@gmail.com> writes:

> Maybe, it'd better to get a real native English speaker review, but
> until he comes, here are my comments:
>
> "how many packages would rebuild"
> "how many packages have to be rebuilt"
>
> "for a number which indicates that a change to"
> "for why your change to"
>
> IANANES...
>
> -- 
> Vincent Legoll

Yes, it was not perfect.  I can do better, but it was just something I
added because I thought it was missing, to open discussion on the
patch.
Aall of the languages I speak including my native one start to sound
weird occasionally when I'm stressed, including but not limited to
"creative" approaches to language.
-- 
♥Ⓐ  ng0
Current Keys: https://we.make.ritual.n0.is/ng0.txt
For non-prism friendly talk find me on http://www.psyced.org

Re: [PATCH] doc: Run guix refresh -l to find out about dependent packages.

[ng0]

Ludovic Courtès <ludo@gnu.org> writes:

> ng0 <ng0@we.make.ritual.n0.is> skribis:
>
>> * doc/contributing.texi (Submitting Patches): Includes an item to
>> explain that core-updates and core-updates-next exist and that your
>> change will be applied on them if it affects too many dependent
>> packages, example: libgcrypt.
>
> In the end I added something a bit more general in commit
> 189b1543cbc2db50e6dd309e84bce4eb503f0493.
>
> Ludo’.

Okay, this reads more general and better with the information you gave
about the branches in the previous message.

Thanks.
-- 
♥Ⓐ  ng0
Current Keys: https://we.make.ritual.n0.is/ng0.txt
For non-prism friendly talk find me on http://www.psyced.org