Re: How can we decrease the cognitive overhead for contributors?

[Giovanni Biscuolo <g@xelera.eu>]

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

Hi all!

I think the discussion about ChangeLog Style shows we probably need to:

1. enhance the manual section "22.6 Submitting Patches"
https://guix.gnu.org/en/manual/devel/en/html_node/Submitting-Patches.html

--8<---------------cut here---------------start------------->8---

Please write commit logs in the ChangeLog format (see Change Logs in GNU Coding Standards); you can check the commit history for examples.

You can help make the review process more efficient, and increase the chance that your patch will be reviewed quickly, by describing the context of your patch and the impact you expect it to have. For example, if your patch is fixing something that is broken, describe the problem and how your patch fixes it. Tell us how you have tested your patch. Will users of the code changed by your patch have to adjust their workflow at all? If so, tell us how. In general, try to imagine what questions a reviewer will ask, and answer those questions in advance.

--8<---------------cut here---------------end--------------->8---

IMO we should move the above paragraphs to a new subsection "22.6.N
Change Logs" and add some rationale (summarized from the GNU Standards
section and maybe with some specific Guix ratio expressed in this
section), a general rule (to be interpreted by humans, see below) and
some examples taken by one or two relevant commits recently made.

2. enhance the section section "22.3 The Perfect Setup" 

The proposed new "22.6.N Change Logs" subsection above should also
provide a link to the relevant information about the snippets documented
in section "22.3 The Perfect Setup"... and /vice versa/: the "snippets
section" should reference the "Change Log" section, since snippets are
made to automate the general rules provided in "Change Log"; I'd also
separate the paragraph related to snippets in a "22.3.1 Emacs snippets"
section

3. wellcome snippets for different IDEs

Somewhere™ in our manual we should say that we are very glad to accept
patches (alco to documentation) to add snippets for free software IDEs
templating systems other than Emacs Yasnippet or Tempel, like
vim-neosnippet for vim or the native templating system of Kate [1], for
example.  Other examples?

4. add a git commit message template

https://www.git-scm.com/book/en/v2/Customizing-Git-Git-Configuration#_commit_template

--8<---------------cut here---------------start------------->8---

If your team has a commit-message policy, then putting a template for that policy on your system and configuring Git to use it by default can help increase the chance of that policy being followed regularly.

--8<---------------cut here---------------end--------------->8---

I'd write a template with a very short explanation on the commit message
*basics* (first line is Subject max 50 chars, blank line, body) and some
https and info link to the relevant section of the manual about Change
Log format.

Suggestions for other git template content are very wellcome.

This template will be added to the git config file etc/git/gitconfig,
that is automatically configured when building the project as stated in
"22.6.1 Configuring Git".

<end of point 4.>

I'll try to send a patchset for 1., 2. and 3; a separate one for 4.

WDYT?

Maxim Cournoyer <maxim.cournoyer@gmail.com> writes:

[...]

>> On 2023-09-06, Liliana Marie Prikler wrote:

[...]

>>> It's 
>>>
>>> * file (variable)[field]<even closer selector>{do you need 4 levels?}

The general form of a ChangeLog Style format for Guix code (Guile with
gexp) could be rewrote as:

* relative-path-of-changed-file (variable) [field] <selector>: Description of change.

I never saw a {4th level} so AFAIU is not needed, unless someone have a
good example plz: in this case we could add a 4th level to the general
description.

[...]

> Here's an example in the Guix "dialect":
>
> --8<---------------cut here---------------start------------->8---
> * gnu/packages/file.scm (package-symbol)
> [arguments] <#:phases>: New patch-paths phase.
> --8<---------------cut here---------------end--------------->8---
>
> It could also have been:
>
> --8<---------------cut here---------------start------------->8---
> * gnu/packages/file.scm (package-symbol) [arguments]: Add patch-paths
> phase.
> --8<---------------cut here---------------end--------------->8---

Those are good general examples: I'd use them in the manual section
descibed in 1.

WDYT?

> It doesn't really matter, as long as it's clear and you did the exercise
> of reviewing the code you touched and writing down the changes summary
> for the reviewer (and yourself).

This is a good example of ratio, I'd use that also :-)

Happy hacking! Gio'



[1] https://docs.kde.org/stable5/en/kate/kate/kate-application-plugin-snippets.html

-- 
Giovanni Biscuolo

Xelera IT Infrastructures

[-- Attachment #2: signature.asc --]
[-- Type: application/pgp-signature, Size: 849 bytes --]