Bug 264562 - New Account Creation Procedure: corrections
Summary: New Account Creation Procedure: corrections
Status: Closed FIXED
Alias: None
Product: Documentation
Classification: Unclassified
Component: Website (show other bugs)
Version: Latest
Hardware: Any Any
: --- Affects Some People
Assignee: freebsd-doc (Nobody)
URL: https://github.com/freebsd/freebsd-do...
Keywords:
Depends on:
Blocks:
 
Reported: 2022-06-09 01:05 UTC by Graham Perrin
Modified: 2022-07-19 02:10 UTC (History)
2 users (show)

See Also:


Attachments

Note You need to log in before you can comment on or make changes to this bug.
Description Graham Perrin freebsd_committer 2022-06-09 01:05:01 UTC
Under <https://www.freebsd.org/internal/new-account/#_mentor_activates_new_committers_commit_bit>: 

> … An entry should also be added to the mentors file in the respective 
> Git repository to indicate the mentor relationship. …

<https://docs.freebsd.org/en/books/handbook/mirror/#admin-branch> is 404; and <https://github.com/freebsd/freebsd-doc/find/main> there's no file named: 

    mentors

I wonder whether this part of the procedure is primarily intended for the first three of the four .dot files at <https://github.com/freebsd/freebsd-src/tree/main/share/misc>: 

    committers-doc.dot
    committers-ports.dot
    committers-src.dot

We have bug 263300 for the fourth file: 

    organization.dot
Comment 1 Graham Perrin freebsd_committer 2022-06-09 01:15:23 UTC
Under <https://www.freebsd.org/internal/new-account/#_additional_services>: 

> … the Conventions and Traditions section.

<https://docs.freebsd.org/en/articles/committers-guide/#> does not refer to the required section. Instead: 

<https://docs.freebsd.org/en/articles/committers-guide/#conventions>
Comment 2 Graham Perrin freebsd_committer 2022-06-09 01:52:32 UTC
<https://docs.freebsd.org/en/articles/committers-guide/#commit-steps> for new committers there's a ten-step

    Procedure 1

– however as far as I can tell, there's no second procedure (2) anywhere in the article. 

For me, as a new committer with a bit for doc, step 5 of 10 should be: 

    src/share/misc/committers-doc.dot

– with mentor approval before the commit. 

----

Pause for thought. Re: comment 0, here's the single-paragraph section of the page in its entirety: 

> After the new committer confirms that the account works, the mentor 
> adds the new committer to the correct access file, using an appropriate 
> commit message. The commit message should at least contain the committer’s 
> full name and username, the mentor’s name and what area the new committer 
> will start to work in. An entry should also be added to the mentors file 
> in the respective Git repository to indicate the mentor relationship. 
> Having done all that, the new committer and mentor jointly go through the 
> first commit operations.

The final sentence is for joint actions, _first_ commit operations. 

For the preceding sentence, it's implicit that addition "to indicate the mentor relationship" is performed by a mentor alone – _not_ a joint action. 

----

However, _joint_ step 5 of 10 is an addition to indicate the mentor relationship. Two examples: 

<https://github.com/freebsd/freebsd-src/commit/b46595affce8c1905c4cd43f1e9853bbb9a4a05f>
<https://github.com/freebsd/freebsd-src/commit/bffc3fb3c09b36fd8740242f184d1e8bd8530920>

If it's true that the new account creation procedure contradicts the Committer's Guide, then I'm inclined to: 

1. treat the setup section of Committer's Guide as definitive

2. make <https://www.freebsd.org/internal/new-account/> 
   consistent, and a little clearer.
Comment 3 commit-hook freebsd_committer 2022-06-26 20:28:08 UTC
A commit in branch main references this bug:

URL: https://cgit.FreeBSD.org/doc/commit/?id=62f6d393eae561326d3846061a24d61aeb4089db

commit 62f6d393eae561326d3846061a24d61aeb4089db
Author:     Sergio Carlavilla Delgado <carlavilla@FreeBSD.org>
AuthorDate: 2022-06-26 20:26:07 +0000
Commit:     Sergio Carlavilla Delgado <carlavilla@FreeBSD.org>
CommitDate: 2022-06-26 20:26:07 +0000

    Fix typos in new account creation procedure

    PR:             264562
    Submitted by:   Graham Perrin <grahamperrin (AT) gmail.com>

 .../en/articles/committers-guide/_index.adoc       |  2 +-
 website/content/en/internal/new-account.adoc       | 29 +++++++++++++++-------
 2 files changed, 21 insertions(+), 10 deletions(-)
Comment 4 Sergio Carlavilla Delgado freebsd_committer 2022-07-14 18:36:21 UTC
I tried to improve the new account creation procedure.
I'm gonna close this PR.
If you think we can improve the procedure even more please open another PR.
Thanks!
Comment 5 Graham Perrin freebsd_committer 2022-07-16 21:26:05 UTC
Thanks, 

(In reply to commit-hook from comment #3)

Under <https://www.freebsd.org/internal/new-account/#_mentor_activates_new_committers_commit_bit> the link: 

    <https://docs.freebsd.org/en/articles/committers-guide//#admin-branch>

– has a superfluous / in the URL, but the link works. 

Under <https://www.freebsd.org/internal/new-account/#_additional_services> the link: 

   <https://docs.freebsd.org/en/articles/committers-guide//#conventions/>

– does not scroll to the required anchor, maybe because there's a 
  trailing /

Instead: 

    <https://docs.freebsd.org/en/articles/committers-guide/#conventions>
Comment 6 Graham Perrin freebsd_committer 2022-07-16 21:30:40 UTC
(In reply to commit-hook from comment #3)

Now I understand why (comment #0) the `mentors` file was not found: 

    internal/admin orphan branch. 

Sergio, thanks again.
Comment 7 Graham Perrin freebsd_committer 2022-07-17 17:37:40 UTC
(In reply to Graham Perrin from comment #5)

<https://reviews.freebsd.org/D35838>
Comment 8 commit-hook freebsd_committer 2022-07-19 02:05:16 UTC
A commit in branch main references this bug:

URL: https://cgit.FreeBSD.org/doc/commit/?id=963f5e07c18cb479b4d2d21b49b2c995ab0eab5a

commit 963f5e07c18cb479b4d2d21b49b2c995ab0eab5a
Author:     Graham Perrin <grahamperrin@FreeBSD.org>
AuthorDate: 2022-07-19 01:43:18 +0000
Commit:     Graham Perrin <grahamperrin@FreeBSD.org>
CommitDate: 2022-07-19 01:43:18 +0000

    New Account Creation Procedure: correct two links

    62f6d393eae561326d3846061a24d61aeb4089db essentially fixed PR 264562,
    however there were three superfluous solidi within URLs. One of the
    three – / at a tail – broke what should have been anchoring.

    PR:                    264562
    Reviewed by:           gjb
    Approved by:           gjb
    Fixes:                 62f6d393eae
                           Fix typos in new account creation procedure
    Differential revision: https://reviews.freebsd.org/D35838

 website/content/en/internal/new-account.adoc | 4 ++--
 1 file changed, 2 insertions(+), 2 deletions(-)