stub doc for maintainers

[phinze]

hey there @caskroom/maintainers - hoping to get some stuff written down about how we do what we do - let me know what you think about this starting point, and then we can get it merged and let some of you fine folks share your wisdom as well! 💌

[phinze]

Oh and anything I wrote in there is up for discussion. I was just spitting out a bunch of stuff to kick off the conversation. So feel free to pick it apart if anything sounds weird to you. 📝

[vitorgalvao]

Some of it read more as a manifesto than a strict document about maintaining, but I actually have no quarrel with that. Your style of writing documentation for this project was always done in a more joyful-over-technical speak and it sounds great here, almost relaxing.

I have no objections to its current form. After the first draft is merged I’d like to start working on Reviewing Incoming Casks, and on the Productivity enhancing tips / tools / scripts that help with PR review, cask testing, etc, as I do have a few that could be useful to more people. Documenting important decisions that have been made also seems the perfect place for adding special-case casks like popcorn-time.

[phinze]

@vitorgalvao Great! You were exactly who I had in mind for laying out how to review Casks like a pro ;) And what can I say, I have a tendency to get manifesto-y. 😀 My guess was that as we fill it in the balance of actual content will help it get back to being overall more of a legit doc. But like I say I'm totally willing to strike anything from the doc that feels out of place. We can see how it evolves.

[tapeinosyne]

There is an uncomfortable limbo between maintainer opinion and documented policy. A set of internal “maintenance guidelines” would be a welcome addition.

[phinze]

Precisely my thinking.

I also just realized that all maintainers can push to this branch, so we can just iterate on this doc with commits! Cool.

[alebcay]

There is an uncomfortable limbo between maintainer opinion and documented policy. A set of internal “maintenance guidelines” would be a welcome addition.

Indeed. In many cases, I will view a PR that I intend to merge, but due to some discrepancies between precedent and documented policy, I will sometimes refrain from proceeding and instead leave it to someone more experienced.

[vitorgalvao]

@alebcay Feel free to, in those cases, just say “I’m not sure about {{whatever_part}}” and ping someone else you think might know. That way we can even give some context (if it is relevant) on why the policy is one way or another.

[rolandwalker]

+1 for the casting of this document as phinzian principles, over protocols.

This is a spare-time project, in which the personnel and processes are always in flux — but the principles should stay unchanged.

Workflow docs are useful too; and we should feel free to amend those liberally as workflows change.

In view of @alebcay's (somewhat surprising) comment, I would moot a workflow guideline along the lines of "Be Bold": merge what you think is right. You can always @mention caskroom/maintainers or an individual to make sure your action gets noticed.

Momentum is supremely important, and every one of the maintainers is qualified to take decisions.

[phinze]

lol ... "phinzian principles"

@rolandwalker that's really great advice. in fact, your walkerian wisdom is commonly a source of guidance and future reference. we should work that into the doc.

i'm cool with focusing first on principles over protocols. and i think you're right that we've always been biased towards momentum, a strategy which has served the project well.

if anybody else feels inspired to push some edits or additions to the doc branch please do! otherwise i will try to work some of this into my next pass.

[rolandwalker]

Merging this as-is in the name of momentum.