Module Lead Maintainers Protocol #301

daviddias · 2018-04-25T09:57:36Z

This PR follows ipfs/team-mgmt#600

Hi y'all, here is an update to our contributing guidelines that introduces a new section based on ipfs/team-mgmt#600 which I would love to have your eyeballs to go over it.

This will require the creation of many PRs to all the js-* repos and if no one is opposed, I would like to get it started :)

Moved tracking table to ipfs/team-mgmt#600 (comment)

jacobheun · 2018-04-25T12:45:42Z

js-code-guidelines.md


-Always run tests before pushing and PR'ing your code.
+- A Tech Lead directs the development of an entire ecosystem of modules (i.e js-ipfs, js-libp2p, js-libp2p and js-multiformats), it has a complete understanding of the stack, the IPFS project, its goals and participates actively in the ROADMAP planning.


There are 2 js-libp2p references, perhaps one should be js-ipld?

jacobheun · 2018-04-25T12:51:03Z

js-code-guidelines.md

-### Linting & Code Style
+- Be proactive in increasing the quality of the module. This goes from improving documentation, tests, codebase and more.
+- Show a great level of rigor and polish in the code that they ship.
+- Help others in understanding how the module and why it exists.


edit: how the module and why it exists to how the module works and why it exists

jacobheun · 2018-04-25T12:53:52Z

js-code-guidelines.md

+- Respect and follow the [IPFS Code of Conduct](https://github.com/ipfs/community/blob/master/code-of-conduct.md).
+- Have a complete understanding of the module purpose, its specification (if any) and how the module is used by other parts of the project.
+- Review and Release PRs
+- Publish new versions of the module to npm


What is the expectation for curating issues? That's probably something we'd want the Lead Maintainers responsible for to make sure we are managing that list to avoid duplicate or stale issues.

Added a note for this one. Thanks for bringing it up

jacobheun · 2018-04-25T13:02:04Z

js-code-guidelines.md

+
+- Update each package.json and README.md to have a `maintainer` field.
+- Update packages table on each entry module (e.g https://github.com/ipfs/js-ipfs#packages) to also list the maintainer for each.
+- Protect the master branch and only grant permissions for merge to the Maintainer and the Tech Lead, only.


This sounds like merge and publish permissions will be limited to 2 people. Has there been any thought about expanding that for larger modules? I see the value around module integrity and quality with a smaller set of responsible individuals, but there is also the risk of only 2 people becoming blockers if they are unavailable during the same period of time (conferences, retreats, vacations, etc).

Fair point, that said, do note that this is 100% for almost every module. I expect that there there will be a few or almost no situation where there is a need for a urgent release without the Tech Lead and the Lead Maintainer being around.

In the case that one or both of the Tech Lead and Lead Maintainer need to be absent for a long period of time, both of these should notify the rest of the group and a plan for releasing during that time should be prepared. My take is that if someone takes a week or two offline during a quiet period, it is almost certainly ok to wait 2 weeks to release, the only exception would be a security fix but those need to be handled with care and in with the the Security team.

olizilla · 2018-04-25T13:09:04Z

js-code-guidelines.md

-Also, remember:
-
-![Barbossa's warning](assets/CodeIsMoreLikeGuidelines.jpg)
+Our toolkit for each of these is not set in stone, and we don't plan to halt our constant search for better tools. Get in touch if you've got ideas. [These are guidelines and rather then rules](assets/CodeIsMoreLikeGuidelines.jpg).


wordo: These are guidelines ~~and~~ rather then rules

These are guidelines rather ~~then~~ than rules

Inception, a wordo inside a wordo! Thanks both! 😀

olizilla · 2018-04-25T13:13:32Z

js-code-guidelines.md

+
+With this structure, we expect to achieve the following goals:
+
+- Recognize extraordinary contributions and empower contributors to take even more important role in the project


wordo: empower contributors to take an even more important role

olizilla · 2018-04-25T13:14:35Z

js-code-guidelines.md

+- Recognize extraordinary contributions and empower contributors to take even more important role in the project
+- Reduce PR review time and Time To Release
+- Increase the overall quality of the project
+- Help users know who to reach out for help


wordo: Help users know who to reach out to for help

alanshaw · 2018-04-25T14:15:36Z

js-code-guidelines.md


-Always run tests before pushing and PR'ing your code.
+- A Tech Lead directs the development of an entire ecosystem of modules (i.e js-ipfs, js-libp2p, js-libp2p and js-multiformats), it has a complete understanding of the stack, the IPFS project, its goals and participates actively in the ROADMAP planning.
+- A Lead Maintainer is a contributor that has showned extraordinary ability to contribute to the project and willingness to make the project better by taking the responsibility of stewarding one of its modules forward.


showned -> shown

achingbrain · 2018-04-25T15:41:38Z

js-code-guidelines.md

+  - [...for maintainers](#for-maintainers)
+    - [Setting up `aegir`](#setting-up-aegir)
+    - [Directory Structure](#directory-structure)
+    - [Default `require`](#default-require)


I don't think this line links to anything.

achingbrain · 2018-04-25T15:42:52Z

js-code-guidelines.md


-For each JavaScript repository in the IPFS, libp2p, IPLD, or related GitHub orgs, there should be a single Captain specified in the Maintainers section of the README for that repository. The Captain is in charge of merging PRs, keeping issues up to date, and overall quality of a repository.
+- [David Dias](http://github.com/diasdavid/) for js-ipfs, js-libp2p js-multiformats ecosystems.
+- [Volker Mische](github.com/vmx) for the js-ipld ecosystem.


Missing the https:// in the link

hugomrdias · 2018-04-26T11:12:02Z

js-code-guidelines.md


-Sometimes, a Captain may elect to have other maintainers that also have merge ability and commit access to the main repo. These maintainers can help out, but defer to the Captain as the person in charge of maintaining quality across the repo. It is important that this distinction is explicit; if there are long-standing PRs or issues, it is ultimately up to the Captain to gather information about the issue or PR. A Captain only makes a decision if he _needs_ to and _all_ methods of discussion are exhausted. Our community strives to trust the Captain as someone who ultimately has the most knowledge of a repo (even if they are also opinionated, and even if they have to spend effort to source that knowledge). This may change in the future, if we go with more non-hierarchical model.
+The current Lead Maintainers can be identified either by the `maintainer` field in the package.json of the module and/or the section `Maintainer` in the README.md of the module.


Also watch for typos as maintainers field exists but is overwritten/handled by npm.

Ref: The "maintainers" field in the top-level of the registry metadata (ie, not versioned) is the npm-controlled list of the npm usernames of the people with permission to write to that package. This can be modified via the npm owners command. (Confusing, I know.)
npm/www#133 (comment)

thanks for catching this. Changed to lead-maintainer instead :)

travisperson

This looks awesome @diasdavid!

pgte

Looks good!

daviddias · 2018-04-30T07:57:35Z

Thanks everyone for the review and positive feedback! I'm super excited for this change \o/

I've issued the first PR to multiformats/js-multihash#51, please double check the permissions I set for Github.

daviddias · 2018-04-30T08:06:37Z

On @vmx's point #301 (review)

I'm sad that it's not about captains anymore ;)

We are still on time to make to change to Captain instead of Lead Maintainer. Add a 👍 for yes or 👎 for no on this comment.

daviddias · 2018-04-30T13:59:12Z

Github perms template from multiformats/js-multihash#51 (comment)

victorb · 2018-05-01T10:15:09Z

I've added the branch protection from js-multihash to all the js-* projects we have now (except one that doesn't have a master branch). You can see a snapshot of the status here: https://ipfs.io/ipfs/QmcAbqYyknVVJbKWihXU1TGNJQ8d3gXuNWpw5vaqizU3cC/status.html

daviddias · 2018-05-01T10:38:20Z

I was 99% convinced with the rename to Captain, but then after applying it to a couple of modules I realized it actually has a very different connotation. We have been using Captain and Tech Lead interchangeably in the past and now using Captain for Lead Maintainer would confuse folks.

daviddias · 2018-05-01T11:08:55Z

@vmx can you handle adding the Lead Maintainers to the IPLD repos?

daviddias · 2018-05-01T12:12:05Z

I declare that the document is now complete. Thank you all for the feedback, testing things and setting up tooling to make the migration smoother.

There is still a lot of PRs to do. I'll try to run through these as fast as possible.

daviddias · 2018-05-01T13:47:29Z

Moved tracking table to ipfs/team-mgmt#600 (comment), merging this PR to get master with the latest guidelines! :)

restructure the doc

050d7ab

daviddias self-assigned this Apr 25, 2018

ghost added the status/in-progress In progress label Apr 25, 2018

Update Tech Lead and Lead Maintainers Section

1e78c2a

daviddias requested review from vmx, pgte, dryajov, olizilla, alanshaw, achingbrain, travisperson, hugomrdias, vasco-santos, fsdiogo, wraithgar, victorb and jacobheun April 25, 2018 12:28

jacobheun reviewed Apr 25, 2018

View reviewed changes

olizilla reviewed Apr 25, 2018

View reviewed changes

alanshaw reviewed Apr 25, 2018

View reviewed changes

alanshaw approved these changes Apr 25, 2018

View reviewed changes

achingbrain reviewed Apr 25, 2018

View reviewed changes

chore: apply doc review

bc75d96

fsdiogo approved these changes Apr 26, 2018

View reviewed changes

hugomrdias reviewed Apr 26, 2018

View reviewed changes

travisperson approved these changes Apr 26, 2018

View reviewed changes

pgte approved these changes Apr 26, 2018

View reviewed changes

use lead-maintainer for package.json instead

85c76b7

daviddias mentioned this pull request Apr 30, 2018

Add lead-maintainer multiformats/js-multihash#51

Merged

daviddias added 2 commits April 30, 2018 09:03

add signed commit clause

efd05ad

typo

0c45154

daviddias mentioned this pull request May 1, 2018

Captain instead of Lead Maintainer multiformats/js-multihash#52

Closed

daviddias force-pushed the module-lead-maintainers branch from b9ed8dc to 0c45154 Compare May 1, 2018 10:36

This was referenced May 1, 2018

Lead maintainer multiformats/js-multiaddr#66

Merged

add lead maintainer multiformats/js-multibase#27

Merged

This was referenced May 1, 2018

Lead maintainer multiformats/js-multicodec#24

Merged

Lead maintainer ipld/js-ipld#127

Merged

Lead maintainer libp2p/js-libp2p#190

Merged

add lead maintainer ipfs/aegir#220

Merged

daviddias changed the title ~~wip: Module Lead Maintainers Protocol~~ Module Lead Maintainers Protocol May 1, 2018

daviddias and others added 2 commits May 1, 2018 13:42

leadMaintainer instead of lead-maintainer

79e91da

docs: Add section about prefered dependency version strategy

635c361

daviddias merged commit 9825cba into master May 1, 2018

ghost removed the status/in-progress In progress label May 1, 2018

daviddias deleted the module-lead-maintainers branch May 1, 2018 13:47

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Module Lead Maintainers Protocol #301

Module Lead Maintainers Protocol #301

daviddias commented Apr 25, 2018 •

edited

Loading

jacobheun Apr 25, 2018

jacobheun Apr 25, 2018

jacobheun Apr 25, 2018

daviddias Apr 26, 2018

jacobheun Apr 25, 2018

daviddias Apr 26, 2018

olizilla Apr 25, 2018

alanshaw Apr 25, 2018

daviddias Apr 26, 2018

olizilla Apr 25, 2018

olizilla Apr 25, 2018

alanshaw Apr 25, 2018

achingbrain Apr 25, 2018

achingbrain Apr 25, 2018

hugomrdias Apr 26, 2018

daviddias Apr 30, 2018

travisperson left a comment

pgte left a comment

daviddias commented Apr 30, 2018

daviddias commented Apr 30, 2018

daviddias commented Apr 30, 2018

victorb commented May 1, 2018

daviddias commented May 1, 2018

daviddias commented May 1, 2018

daviddias commented May 1, 2018

daviddias commented May 1, 2018


		Always run tests before pushing and PR'ing your code.
		- A Tech Lead directs the development of an entire ecosystem of modules (i.e js-ipfs, js-libp2p, js-libp2p and js-multiformats), it has a complete understanding of the stack, the IPFS project, its goals and participates actively in the ROADMAP planning.


		With this structure, we expect to achieve the following goals:

		- Recognize extraordinary contributions and empower contributors to take even more important role in the project


		Sometimes, a Captain may elect to have other maintainers that also have merge ability and commit access to the main repo. These maintainers can help out, but defer to the Captain as the person in charge of maintaining quality across the repo. It is important that this distinction is explicit; if there are long-standing PRs or issues, it is ultimately up to the Captain to gather information about the issue or PR. A Captain only makes a decision if he _needs_ to and _all_ methods of discussion are exhausted. Our community strives to trust the Captain as someone who ultimately has the most knowledge of a repo (even if they are also opinionated, and even if they have to spend effort to source that knowledge). This may change in the future, if we go with more non-hierarchical model.
		The current Lead Maintainers can be identified either by the `maintainer` field in the package.json of the module and/or the section `Maintainer` in the README.md of the module.

Module Lead Maintainers Protocol #301

Module Lead Maintainers Protocol #301

Conversation

daviddias commented Apr 25, 2018 • edited Loading

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

travisperson left a comment

Choose a reason for hiding this comment

pgte left a comment

Choose a reason for hiding this comment

daviddias commented Apr 30, 2018

daviddias commented Apr 30, 2018

daviddias commented Apr 30, 2018

victorb commented May 1, 2018

daviddias commented May 1, 2018

daviddias commented May 1, 2018

daviddias commented May 1, 2018

daviddias commented May 1, 2018

daviddias commented Apr 25, 2018 •

edited

Loading