Write a maintainer's guide

[waldyrious]

We need to have a well-defined (public) procedure for handling PRs, since there's a chronic issue of a PR backlog we can't seem to get rid of entirely. It could be something like:

• PRs will be merged once they (1) pass the automated tests (Travis CI and CLA signing) without issues, (2) have the review comments addressed (3) get the thumbs-up of two maintainers -- the second one can do the merging immediately after accepting.
• If a week goes by after (1) and (2) are satisfied, but no second maintainer has manifested their approval, the first maintainer can merge.
• If a month goes by without reaction from the submitter (e.g. to fix lint errors or review comments), the PR should be taken over by a maintainer who should ensure that at least the page conforms to the contribution guidelines and passes Travis CI before merging.
  • Here, "taking over" means making any necessary changes, including rebase, reword of commit messages, and change of content, while preserving the authorship metadata (e.g. by amending commits rather than copy-pasting the content)

This should ensure we remain responsive to contributions, and that contributors have a clear notion of what to expect (and when to call out maintainers if they fail to adhere :P)

Any thoughts? Did I miss something?

[agnivade]

Agree on all points. 💯

I do have some concerns on the 3rd point though. I had spent quite some time merging old PRs. And it seems like the backlog is building up again. Now, I just don't feel like doing the whole exercise again. 😞 And imposing the task of making the necessary changes(which might include reading up the man page and studying the command) to the maintainers is a bit unfair I believe.

I absolutely want to remain responsive to contributions so that everyone feels like they can contribute. But, when a contributor does not respond even after pinging separately, it becomes a bit difficult to go through the task of merging the PR time and again.

[waldyrious]

We can leave it at the discretion of the maintainers: the explicit guidelines would make it clear to everyone when the maintainers could override a PR's author without stepping on any toes, but that would be a right, not a duty. This way, if merging the PR would entail too much work, it would be ok to simply close the PR with a note to that effect. Sounds good?

[agnivade]

Again, "too much work" is a subjective thing. But yea, I am leaning towards the fact that its okay for us to close a PR, after pinging the contributor and waiting for one week after no response.

[waldyrious]

Sure, the ideia is that either resolution would be acceptable (and predictable), so maintainers would have the option to choose whatever they deem appropriate given the specifics of the situation.

[agnivade]

Great. Where do you think we should put this ?

[waldyrious]

I'm thinking of adding this to a GOVERNANCE.md page (something quite simple and free-form -- just a list of the guidelines for maintainership and handling of issues and PRs that we've been following so far). This would also serve as a great place to implement #1117.

Before going ahead, I'd like to hear someone else's opinion -- at least @Ostera's.

[waldyrious]

In the meantime, @agnivade, do you think we could repurpose @tldr-bot to (also) perform the necessary pinging after the periods we define here expire? You've been doing that manually, but we should automate as much of this activity as possible, so as to free up contributor/maintainer time for the actual changes :)

The bot could even close PRs as you did in #975 -- the wording you used there seems like a great template we could adopt: friendly, informative, and with clear action paths for alternative resolution.

[agnivade]

That sounds like a nice idea for a new project. I don't think there are any tools currently which do that(need to check though).

However, we still have to resolve the original problem of tldr-bot (the issue of it not getting the token for PRs coming from a different repo). Getting a separate server for ourselves seems to be the only way to go.

[waldyrious]

Sure. I guess @Ostera also could have something to say here :)

I wonder if there's any host for server-side services that offers a free plan for FOSS projects, though, like Travis and others do for the CI side of things. Any ideas?

[agnivade]

We could use heroku, but their free tier is too poor. Don't know about any other services.

[jeeftor]

Could ya'll also add more maintainers? How many of you guys are actually active?

[agnivade]

Could ya'll also add more maintainers?

Yea absolutely. I have been thinking of adding new ppl. More thoughts on that here - #1117.

How many of you guys are actually active?

Me and @waldyrious usually are. @Ostera also chimes in from time to time.

Will you be interested in joining as a member ? 😉 Don't hesitate to hop on to our gitter channel if you have more questions.