[NeXus-committee] [EXTERNAL] Re: Pull request etiquette

[Zhang, Chen]

In our group, we setup pull request template and issue templates for each repo (can also be done at the org level), and the template contains the instructions on how to proceed. In the extreme case, `lmfit` has a very good example on how to **force** contributors to follow the instructions:

https://github.com/lmfit/lmfit-py/blob/master/.github/ISSUE_TEMPLATE.md
https://github.com/lmfit/lmfit-py/blob/master/.github/PULL_REQUEST_TEMPLATE.md

Cheers,
Chen

--
Chen Zhang
Computational Scientist
Computing and Computational Sciences Directorate
Oak Ridge National Lab

From: NeXus-committee <nexus-committee-bounces at shadow.nd.rl.ac.uk> on behalf of Paul Millar via NeXus-committee <nexus-committee at shadow.nd.rl.ac.uk>
Date: Tuesday, October 22, 2024 at 12:53 PM
To: nexus-committee at nexusformat.org <nexus-committee at nexusformat.org>
Subject: [EXTERNAL] Re: [NeXus-committee] Pull request etiquette
Just FYI,

Information on how people may contribute to a project is (by convention)
often recorded in the 'CONTRIBUTING' or 'CONTRIBUTING.md' file (if
markdown is used).  This is a file stored in the repo's root directory,
much like README / README.md.

Amongst other things, the 'CONTRIBUTING.md' file often describes what is
expected when proposing a change.  So, a policy requiring that an issue
is created first would (I think) naturally be documented in that file.

HTH,
Paul.

On 22/10/2024 02.05, Aaron Brewster via NeXus-committee wrote:
> Thirded!  For all the above reasons.
>
> On Fri, Oct 18, 2024 at 10:30 AM Pete Jemian via NeXus-committee
> <nexus-committee at shadow.nd.rl.ac.uk> wrote:
>
>     I second this as the minimum requirement. Every PR should
>     reference an issue.
>
>     Issues describe "why" this is important.
>
>     PRs describe "how" the issue is handled.
>
>     The most expensive question is "why". In current practice, this
>     context is omitted far too often.
>
>
>     On Fri, Oct 18, 2024, 11:38 AM Osborn, Raymond via NeXus-committee
>     <nexus-committee at shadow.nd.rl.ac.uk> wrote:
>
>         I would like to suggest that we require all pull requests to
>         have a detailed description of what is being proposed and why.
>         It is becoming impossible to understand the context of many of
>         the PRs, whose conversations fill my inbox every day.
>         Sometimes there are links to other related PRs or issues, but
>         these often contain no description either.
>
>         I think the assumption is that these are things that were
>         either discussed at the recent NIAC or in a telco, but even if
>         we were present, it can be difficult to remember them all and
>         those who weren’t present have no chance of knowing what is
>         going on. Detailed descriptions are also important as a
>         historical record of why we make the decisions that we do.
>
>         Ray
>
>         --
>         Ray Osborn, Senior Scientist
>         Materials Science Division
>         Argonne National Laboratory
>         Lemont, IL 60439, USA
>         Phone: +1 (630) 252-9011
>         Email: ROsborn at anl.gov
>
>         _______________________________________________
>         NeXus-committee mailing list
>         NeXus-committee at nexusformat.org
>         https://urldefense.us/v2/url?u=https-3A__lists.nexusformat.org_mailman_listinfo_nexus-2Dcommittee&d=DwIGaQ&c=v4IIwRuZAmwupIjowmMWUmLasxPEgYsgNI-O7C4ViYc&r=oSSxa7CTOFRP-tS_6Kp7Gw&m=NKa4ti00538uOxZxa84PPoobuZT-I4rwGOw_ghlEZb-FlYiNoRKQjmRoJmJpvLO7&s=ImsBZ0o0-AesJ7LLuP1CQahmjUl6eph0sdSAKInrCRU&e=
>
>     _______________________________________________
>     NeXus-committee mailing list
>     NeXus-committee at nexusformat.org
>     https://urldefense.us/v2/url?u=https-3A__lists.nexusformat.org_mailman_listinfo_nexus-2Dcommittee&d=DwIGaQ&c=v4IIwRuZAmwupIjowmMWUmLasxPEgYsgNI-O7C4ViYc&r=oSSxa7CTOFRP-tS_6Kp7Gw&m=NKa4ti00538uOxZxa84PPoobuZT-I4rwGOw_ghlEZb-FlYiNoRKQjmRoJmJpvLO7&s=ImsBZ0o0-AesJ7LLuP1CQahmjUl6eph0sdSAKInrCRU&e=
>
>
> _______________________________________________
> NeXus-committee mailing list
> NeXus-committee at nexusformat.org
> https://urldefense.us/v2/url?u=https-3A__lists.nexusformat.org_mailman_listinfo_nexus-2Dcommittee&d=DwIGaQ&c=v4IIwRuZAmwupIjowmMWUmLasxPEgYsgNI-O7C4ViYc&r=oSSxa7CTOFRP-tS_6Kp7Gw&m=NKa4ti00538uOxZxa84PPoobuZT-I4rwGOw_ghlEZb-FlYiNoRKQjmRoJmJpvLO7&s=ImsBZ0o0-AesJ7LLuP1CQahmjUl6eph0sdSAKInrCRU&e=

_______________________________________________
NeXus-committee mailing list
NeXus-committee at nexusformat.org
https://urldefense.us/v2/url?u=https-3A__lists.nexusformat.org_mailman_listinfo_nexus-2Dcommittee&d=DwIGaQ&c=v4IIwRuZAmwupIjowmMWUmLasxPEgYsgNI-O7C4ViYc&r=oSSxa7CTOFRP-tS_6Kp7Gw&m=NKa4ti00538uOxZxa84PPoobuZT-I4rwGOw_ghlEZb-FlYiNoRKQjmRoJmJpvLO7&s=ImsBZ0o0-AesJ7LLuP1CQahmjUl6eph0sdSAKInrCRU&e=
-------------- next part --------------
An HTML attachment was scrubbed...
URL: <https://lists.nexusformat.org/pipermail/nexus-committee/attachments/20241022/ab82642b/attachment.htm>