Local list of maintainers in CONTRIBUTING.md?

[wking]

In #170 we landed the following text:

The list of maintainers on the Software Carpentry website lists the people currently responsible for managing this repository.

The shell PR that inspired #70 was swcarpentry/shell-novice#68, which had:

The maintainers for this repository are Christina Koch and Gabriel Devenyi.

and the shell lesson still lists the maintainers locally. Can we switch this repository to list it's maintainers, and then have downstream maintainers update that line to list temselves? We're already doing something like this for list of issues link target.

Personally, I find the local listing better because:

a. Maintainers have push access to their local CONTRIBUTING.md, so they can update that listing without needing to bother a swcarpentry/site maintainer.
b. It's one less bit of information to list on http://software-carpentry.org/lessons.html, which already has enough going on. I'm all for raising awareness of the contribution maintainers are making, but I think a listing in the lesson's CONTRIBUTING.md is sufficiently high-profile.
c. It avoids ambiguity about things like our turtles lesson. Is that maintained by Trevor Bekolay and Azalee Bostroem (the “Python” maintainers)? Similarly, it's unclear who's maintaining this repository. Does it fall under “tools”? Does swcarpentry/amy fall under “tools”? It's easier to handle the mapping between repositories and maintainers if the maintainers are listed in the repositories themselves.

Finally, there's a lot going on right now in SWC-land, so feel free to just let this issue sit until we have the time and energy to address it. I'm just filing it now because we bumped into the turtles case for swcarpentry/DEPRECATED-site#870, but I don't think it's particularly critical.

[jdblischak]

My main concern about this is merge conflicts. If a lesson maintainer modifies this file such that it points to the issues of their repo and lists them as the maintainer, the next time this file gets edited, there will be a merge conflict when pulling from the core branch of lesson-template.

[jdblischak]

Forgot to mention. The way we are currently handling this in r-novice-inflammation is to have an additional contributing section in the README. In this section it links to the issues of that repo, links to the generic CONTRIBUTING.md, and gives directions that are specific for that repo (and I should probably list the lesson maintainers, too).

[gvwilson]

On 2015-03-10 8:15 PM, John Blischak wrote:

The way we are currently handling this in r-novice-inflammation is to
have an additional contributing section in the README
https://github.com/swcarpentry/r-novice-inflammation#contributing.
In this section it links to the issues of that repo, links to the
generic CONTRIBUTING.md, and gives directions that are specific for
that repo (and I should probably list the lesson maintainers, too).

I like that.

[wking]

On Tue, Mar 10, 2015 at 08:11:55PM -0700, John Blischak wrote:

My main concern about this is merge conflicts…

I don't expect the lesson-template maintainers to have such rapid
churn that this is a recurring issue. If the lesson maintainers (or
whoever is handling the core merges 1) has to resolve a matainer
change conflict once a year (or once every two, or however often
lesson-template maintainers turn over), I doubt it will be a major
fraction of their SWC time.

If a lesson maintainer modifies this file such that it points to the
issues of their repo and lists them as the maintainer, the next time
this file gets edited, there will be a merge conflict when pulling
from the core branch of lesson-template.

Only if the upstream edits and the local edits overlap. If the
three-line context buffer around the change is sufficient padding
(e.g. core bumps something at the top of the file, and you have local
changes at the bottom of the file), then Git will happily merge both
sets of changes without asking for assistance.

Tue, Mar 10, 2015 at 08:15:17PM -0700, John Blischak:

…In this section it links to the issues of that repo, links to the
generic CONTRIBUTING.md,…

That means that folks contributing to your lesson see 2:

If you're looking for things to work on, please see the list of
issues for this repository, …

linking to lesson-template, which is probably not where you keep
issues for your lesson ;).

While I'm happy to jump through some hoops to avoid merge conflicts, I
think that making CONTRIBUTING.md off limits to downstream lessons is
more trouble than it's worth.

[jdblischak]

It's not clear to me why there is a link to the Issues in lesson-template in the first place. This CONTRIBUTING.md describes how to contribute to a lesson repo that is a clone of the lesson-template.

For example, the following two lines describe downstream lesson repos, and not the lesson-template repo itself:

For our lessons, you should branch from and submit pull requests against the gh-pages branch.

This isn't true for lesson-template. Changes to the core files should be filed against the core branch.

This lesson is based on the template found at https://github.com/swcarpentry/lesson-template. That repository has instructions on formatting and previewing lessons.

The lesson-template repo isn't based off of itself.

Overall this is a strange situation. We have a CONTRIBUTING.md in one repo, that is supposed to describe how to contribute not to itself, but to downstream repos. Currently it is a mix of the two. So I'd be in favor of taking out the hyperlink to Issues. Then the sentence will apply to all downstream repos.

[wking]

On Wed, Mar 11, 2015 at 05:24:52AM -0700, John Blischak wrote:

Overall this is a strange situation. We have a CONTRIBUTING.md in
one repo, that is supposed to describe how to contribute not to
itself, but to downstream repos.

I agree, but I'd rather the fix be making CONTRIBUTING.md actually
apply to lesson-template, but with an eye to making life easy for
downstream lesson maintainers. I can open a PR with some suggested
text if this sounds reasonable. Having a CONTRIBUTING.md that does
not apply to the repository that contains it seems like it would
cause confusion ;).

However, having a localized CONTRIBUTING.md is mostly orthogonal to
whether or not we want to list the maintainers somewhere in the
repository that they're maintaining, vs. linking to an external
maintainers list, which is the main question I'm asking in this issue.
Does anyone see a drawback to locally listing maintainers besides “we
don't want to cause merge conflicts”?

[gvwilson]

I expected lesson authors to modify CONTRIBUTING.md (e.g., change the
links for issues etc.) for each of their lessons. If that's not clear,
we can (a) clarify and (b) add something to the validator to complain if
they haven't done it.

[gvwilson]

+1 on locally maintaining contributors - we want to make it easy for people to build lessons using our templates + tools that aren't part of SWC core, and a centralized contributor list directly contradicts that.

[wking]

On Wed, Mar 11, 2015 at 10:21:59AM -0700, Greg Wilson wrote:

+1 on locally maintaining contributors…

I'm happy to work up or review a PR for this (whichever is more
helpful). Who gets listed for this repository?

[gvwilson]

@wking can you please add a script to the 'tools' directory that'll list names of contributors via `git log` and other magic? That'll give people a starting point...

[wking]

On Wed, Mar 11, 2015 at 10:35:35AM -0700, Greg Wilson wrote:

@wking can you please add a script to the 'tools' directory that'll list
names of contributors via git log and other magic? That'll give
people a starting point...

For listing the maintainers? Looking at just folks merging into the
mainline here we have:

$ git shortlog -s --first-parent origin/core
1 Aaron O'Leary
2 Andy Boughton
47 Greg Wilson
1 James Allen
1 John Blischak
16 Raniere Silva
1 abought

Expanding to include gh-pages gives us:

$ git shortlog -s --first-parent origin/core
1 Aaron O'Leary
2 Andy Boughton
1 Carol Willing
3 Francois Michonneau
62 Greg Wilson
1 Ivan Gonzalez
20 Raniere Silva

If you don't like calling Git directly, and really want a middleman
script to call Git and list all contributors (not just folks
contributing to the first-parent history), I recommend my
update-copyright script 1.

[gvwilson]

I think for most lessons we'll want gh-pages - core is just for the template (and we can handle that specially). A script that gives what you believe to be the most useful answer would be very welcome.

[wking]

On Wed, Mar 11, 2015 at 10:53:15AM -0700, Greg Wilson wrote:

A script that gives what you believe to be the most useful answer
would be very welcome.

Most useful for guessing maintainers?

[gvwilson]

Most useful for giving people who've contributed the credit they deserve.

[wking]

On Wed, Mar 11, 2015 at 10:58:54AM -0700, Greg Wilson wrote:

Most useful for giving people who've contributed the credit they
deserve.

Done in #197.

After re-reading your earlier comment 1, I see you were +1ing
locally listing contributors, but not speaking to locally listing
(or not) maintainers. Where do we stand on that?

[jdblischak]

I expected lesson authors to modify CONTRIBUTING.md (e.g., change the links for issues etc.) for each of their lessons. If that's not clear, we can (a) clarify and (b) add something to the validator to complain if they haven't done it.

If CONTRIBUTING.md is meant to be edited for each of the lessons, shouldn't it only be present in the gh-pages branch? It was my understanding that the core branch was only supposed to contain files that are shared across lesson repos.

[wking]

On Wed, Mar 11, 2015 at 08:27:29PM -0700, John Blischak wrote:

I expected lesson authors to modify CONTRIBUTING.md (e.g., change
the links for issues etc.) for each of their lessons…

If CONTRIBUTING.md is meant to be edited for each of the lessons,
shouldn't it only be present in the gh-pages branch? It was my
understanding that the core branch was only supposed to contain
files that are shared across lesson repos.

I think we want a CONTRIBUTING.md in the core branch because:

1. We want to lay out how to contribute to the core branch.
   CONTRIBUTING.md is where GitHub wants us to put that information
   1, and an in-branch version ensures folks contributing to core
   from the command line don't miss it.
2. Localizing CONTRIBUTING.md for a particular lesson should require
   minimal changes (just the issues link and any local listing of
   maintainers, as far as I can tell).
3. The lesson-template version of CONTRIBUTING.md should be very
   stable, so conflicts with the downstream changes should be few and
   far-between (once we work out kinks like this issue).

[wking]

So the only argument I've seen against having a localized
maintainer listing is @jdblischak's concern about merge conflicts
1, which I tried to rebut 2. Then we had a detour into a
localized issue link (see also #214), and I tried to refocus the
discussion on whether we want a local maintainer listing 3.
Then we had a detour into a localized contributor listing (see
#197) and a detour into what branch CONTRIBUTING.md should be
living in. In the interest of closing this one out, I'd like to
take another stab at refocusing discussion on a local maintainer
listing. I'd suggest we tackle this in two stages:

1. Do we want this? I outlined the reasons I want it when I opened
   this issue. I haven't heard any arguments against it, so I expect
   this will be fairly uncontroversial.
2. Where do we want this to live? I think it should be in
   CONTRIBUTING.md, but if we can't resolve concerns about merge
   conflicts there I'm happy to put it somewhere else.

[wking]

On Sat, Mar 28, 2015 at 12:14:20PM -0700, W. Trevor King wrote:

1. Do we want this? I outlined the reasons I want it when I opened
   this issue. I haven't heard any arguments against it, so I expect
   this will be fairly uncontroversial.
2. Where do we want this to live? I think it should be in
   CONTRIBUTING.md, but if we can't resolve concerns about merge
   conflicts there I'm happy to put it somewhere else.

I usually wait at least a week between bumps, but it's been five quiet
days now so it doesn't seem too soon ;). As another example of
point (c) in my comment opening this issue, I'm not sure who's
maintaining swcarpentry/instructor-training. It's not listed on our
central maintainer list 1. I'd have guessed @gvwilson, but he's had
carpentries/instructor-training#8 open for a week and a half without
moving on it (which certainly feels like a long enough wait for
feedback before merging a change into a repository you maintain
yourself). There's also an uncommented PR from early January
(carpentries/instructor-training#2). Who do I ping about getting that
repository moving again? Is @gvwilson the only maintainer? There's
no first-parent activity by anyone else in that repository since it
split off from lesson-template. Is there anyone else interested in
maintaining that repository? @BillMills seems fairly active on the
instructor-training front. Maybe he could pick it up? Where do these
sorts of questions get hashed out? I think local maintainer listings
would make it easier for folks to handoff responsibilities. “Sorry
everyone, but I'm too swamped to maintain this repository. Does
anyone else want to take over?” would be a good
swcarpentry/instructor-training issue, hit all
swcarpentry/instructor-training watchers, and be resolvable by a
swcarpentry/instructor-training pull request.

[gvwilson]

Apologies, but fundraising is ahead of this in queue right now.

[wking]

On Thu, Apr 02, 2015 at 11:44:12AM -0700, Greg Wilson wrote:

Apologies, but fundraising is ahead of this in queue right now.

Is there any way to move the orphaned repositories forward while
you're focusing on fundraising? For example, after you ok-ed general
merge access to amy 1, I nominated Piotr as the new maintainer 2
and he agreed [3](or at least that's how I read that exchange).

[gvwilson]

Now that lesson-template and lesson-example are separate, we can require a level-2 section in README.md called "Maintainers" with a bullet list of the lesson's maintainers:

## Maintainers

*   Trevor King (@wking)
*   John Blischak (@jdblischak)

The validator can check for it (cc @abought and @r-gaia-cs for confirmation), and there won't be merge conflicts when updating from lesson-template (because lesson-template doesn't have a README). Workable?

[wking]

On Sat, Apr 04, 2015 at 12:17:11PM -0700, Greg Wilson wrote:

Now that lesson-template and lesson-example are separate, we can
require a level-2 section in README.md called "Maintainers" with a
bullet list of the lesson's maintainers…

This works for me.

… there won't be merge conflicts when updating from lesson-template
(because lesson-template doesn't have a README)…

I'd consider adding a README.md that just says something like:

A shared template for Software Carpentry lessons. See [docs][] for
details.

[docs]: path-to-docs, e.g. doc/template/README.md

Because it's good to have something up as a landing page. Ideally
that will be something like the above which we can write once and then
never change again. Folks who are already downstream would have a
single merge-conflict on README.md when they pulled that in, but it's
a conflict that will be easy to resolve:

$ git checkout HEAD -- README.md
$ git add README.md
$ git merge # to finish off the conflicting pull

See #124 (and it's post core→gh-pages #215) for details on the doc idea.

[rgaiacs]

The validator can check for it (cc @abought and @r-gaia-cs for confirmation)

+1

[wking]

On Sat, Apr 04, 2015 at 12:17:11PM -0700, Greg Wilson wrote:

Now that lesson-template and lesson-example are separate, we can
require a level-2 section in README.md called "Maintainers" with a
bullet list of the lesson's maintainers:

## Maintainers

*   Trevor King (@wking)
*   John Blischak (@jdblischak)

As a trial implementation of this approach, I've just submitted #223
to remove the CONTRIBUTING.md reference to the central listing, and
then the follow-on carpentries/lesson-example#2 to pull #223 into the
lesson-example repository and add the lesson-example maintainers to
its README.md. If we like those PRs, I can go around and submit
similar maintainer notes to our other lesson-template consumers. And
maybe remove the central listing to stay DRY? And maybe add
maintainer notes to our non-lesson repositories
(e.g. swcarpentry/workshop-template)?

[rgaiacs]

@wking Can we close this?

[wking]

On Sun, Apr 19, 2015 at 06:53:57AM -0700, Raniere Silva wrote:

@wking Can we close this?

The trial-run PRs both landed, so I'm fine closing this.

Future action after we close this issue:

• I'll PR other lessons I'm involved with to give them local
  maintainers.
• If it ends up bugging me or going stale, I'll open a separate issue
  in swcarpentry/site to remove or update (or auto-update?) the
  central maintainer listing.