Page MenuHomeFreeBSD

Add a note about what a maintainer is not.
ClosedPublic

Authored by mat on Jul 3 2014, 4:55 PM.

Diff Detail

Repository
rD FreeBSD doc repository - subversion
Lint
No Linters Available
Unit
No Unit Test Coverage

Event Timeline

mat retitled this revision from to Add a note about what a maintainer is not. Compiled version available at: http://aragorn.in.absolight.net/d/en_US.ISO8859-1/books/porters-handbook/makefile-maintainer.html.
mat updated this object.
mat edited the test plan for this revision. (Show Details)

I'm not sure custodian is the right word, reading the American oxford definition, it feels right, but I can replace it with person which is more generic.

Also, this goes somewhere in the committers handbook, not here, but we should add:

Commit messages are expected to be in English.

Committers are expected to be reachable by their @FreeBSD.org email address in order to facilitate maintainership of the ports and ensure committers are up to date on changes to the ports tree infrastructure (and/or discussions of proposed changes to the ports infrastructure), and other changes as they are announced.

en_US.ISO8859-1/books/porters-handbook/makefiles/chapter.xml
2738

Grammar: This should be "... who the community looks to to take care of the port..." but then that's a (grammatically correct) double word, which sometimes gets flagged (I think igor might flag this for example) and is also somewhat confusing. Perhaps rewording to:

The community first looks to the maintainer to take care of the port, but the maintainer is not the only one who may do so.

would be good?

2742

Perhaps add:

Changes to a port are not solely limited to the port maintainer. There are many others who may make changes to any port, such as the FreeBSD Ports Management Team or members of other teams. Other committers may also make changes to any port to fix dependency or other issues caused by changes they are making, such as updating a shared library. Additionally, there are some types of fixes that are approved for any committer to make to any port.

This might be a good place to document the blanket approvals if we plan to keep them forever.

wblock added inline comments.
en_US.ISO8859-1/books/porters-handbook/makefiles/chapter.xml
2722

"Note" is used way too much, remove it.

"Only a single address..."

2723–2724

s/should be/is/

2723–2724

s/your/a/ to avoid use of "you" and "your".

2724–2727

I like emdashes, but this is simpler as two sentences.

"this entry. That merely..."

2730

The maintainer is responsible for keeping the port up to date and making sure that it works correctly.

2734

"section" seems superfluous there, can just be removed.

2738

How about

A maintainer volunteers to keep a port in good working order. Maintainers have the primary responsibility for their ports, but not exclusive ownership. Ports exist for the benefit of the community and, in reality, belong to the community. What this means is that people other than the maintainer can make changes to a port. Large changes to the Ports Collection might require changes to many ports. The &os; Ports Management Team or members of other teams might modify ports to fix dependency issues or other problems, like a version bump for a shared library update. Some types of fixes have <quote>blanket approval</quote>, allowing any committer to fix those categories of problems on any port.

mat retitled this revision from Add a note about what a maintainer is not. Compiled version available at: http://aragorn.in.absolight.net/d/en_US.ISO8859-1/books/porters-handbook/makefile-maintainer.html to Add a note about what a maintainer is not..
mat updated this object.

Update with Steve and Warren's changes.

en_US.ISO8859-1/books/porters-handbook/makefiles/chapter.xml
2782

Seems like this should be qualified now. The note we just changed says that many changes already have approval. Are those changes still supposed to be sent to the maintainer before commit?

In D342#12, @wblock wrote:

Seems like this should be qualified now.

I agree!

The note we just changed says that many changes already have approval. Are those changes still supposed to be sent to the maintainer before commit?

Nope!

Tiny addition of the word "minor":
" What this means is that people other than the maintainer can make minor changes to a port." That should probably be enough to get the meaning across and there's no need to explicitly describe that those changes should not change the function, logic, etc of the port.

The blanket approvals should be documented somewhere that is not a blog post. This is a very static document and the blankets may change, so maybe better on a wiki page with a link from here.

In D342#14, @erwin wrote:

Tiny addition of the word "minor":
" What this means is that people other than the maintainer can make minor changes to a port." That should probably be enough to get the meaning across and there's no need to explicitly describe that those changes should not change the function, logic, etc of the port.

I agree, but on person's definition of "minor" is another persons excuse to start a flame war, so if you mean changes that don't change the functionality of the port it might be good to explicitly state than.

The blanket approvals should be documented somewhere that is not a blog post. This is a very static document and the blankets may change, so maybe better on a wiki page with a link from here.

Agree!

In D342#14, @erwin wrote:

The blanket approvals should be documented somewhere that is not a blog post. This is a very static document and the blankets may change, so maybe better on a wiki page with a link from here.

I kinda disagree, changing this document is just as easy as changing a wiki :-)

Add the blanket approval.

Add the blanket approval.

en_US.ISO8859-1/books/porters-handbook/makefiles/chapter.xml
2751

This sentence and the last one in the paragraph above should be combined. The list of blanket approvals ought to be inside the note.

2752

&a.portmgr; and do not require maintainer approval.

2753

The list of exceptions should be a separate sentence, and not an aside.

Blanket approvals do not apply to some ports that are maintained by teams like ...
These teams use external repositories and can have work that would conflict with blanket approvals.

Blanket approval for most ports applies to these types of fixes:

2763

The FDP Primer says to use American spellings unless the document used all British spellings originally, so s/modernising/modernizing/ .

In D342#17, @mat wrote:
In D342#14, @erwin wrote:

The blanket approvals should be documented somewhere that is not a blog post. This is a very static document and the blankets may change, so maybe better on a wiki page with a link from here.

I kinda disagree, changing this document is just as easy as changing a wiki :-)

Not for me! :)

One more round of update.

en_US.ISO8859-1/books/porters-handbook/makefiles/chapter.xml
2751

Mixed both paragraphs.

2763

I think I wrote modernizing, thought the z was making the word look ugly and replaced it with an s 0:-)

In D342#23, @swills wrote:

Not for me! :)

Don't tell me you're scared of a few < and > :-p

en_US.ISO8859-1/books/porters-handbook/makefiles/chapter.xml
2749

s/Those/These/

2750

s/approval/approvals/

2757

Well, not conflict with the approvals, but with the type of changes that fall under blanket approvals. So maybe

...conflict with changes that would normally fall under blanket approval.</para>

2759

s/Approval/approval/

2780

"of a port" is not needed.

en_US.ISO8859-1/books/porters-handbook/makefiles/chapter.xml
2751

Oops, my fault! I meant plural on the second one, not the first.

approval from the maintainer. Blanket approvals do not apply

or alternately

approval from the maintainer. Blanket approval does not apply

mat added a reviewer: mat.

Committed in r45207.

This revision is now accepted and ready to land.Jul 4 2014, 4:48 PM