Improve project organization by shykes · Pull Request #9137 · moby/moby

shykes · 2014-11-13T04:34:16Z

Proposed improvements to project organization.

This organization change has 3 goals:

Make the project more open and accessible
Make the project more scalable
Do this in an incremental way, without unnecessary refactoring

The actual organization change is covered in 6a99b8dea935be9228a47c84bcbfb7491e6e5584. Cosmetic changes are discussed in #9177 and #9178

SvenDowideit · 2014-11-13T05:07:00Z

MAINTAINERS

fredlf :)

ah, ok, references to the [people] huh

crosbymichael · 2014-11-13T05:14:59Z

From a first pass content looks good. I'll ping @tianon here because the renaming of hack to project probably breaks some things in the build scripts or for packagers. Just something for us to double check before a merge.

crosbymichael · 2014-11-13T05:19:42Z

project/MAINTAINERS.md

jessfraz · 2014-11-13T15:34:42Z

SGTM just probably need to do a sed for the hack/project change

shykes · 2014-11-13T18:16:36Z

I put a symlink for now :)

On Thursday, November 13, 2014, Jessie Frazelle notifications@github.com
wrote:

SGTM just probably need to do a sed for the hack/project change

—
Reply to this email directly or view it on GitHub
#9137 (comment).

tianon · 2014-11-13T20:07:42Z

I'd bring back up #3502. 😉

tianon · 2014-11-13T20:08:22Z

(some of which is somewhat outdated now)

tianon · 2014-11-13T20:14:06Z

MAINTAINERS

Not a big fan of the format here -- what's the rationale for it being so complex? I like the extra information, but it's not very easy to read and seems like it's going to be very error-prone to update unless we've got tooling verifying correctness.

For example, one of the things that's great about the current MAINTAINERS syntax is that it's trivial to programmatically parse reasonably, even if all you've got is POSIX shell.

The rationale is to only define all this once, and then refer to people only by their canonical nickname as defined in people. This is useful because people tend to wear multiple hats. It's also better than defaulting to people's github handle. Sometimes people have different handles in irc, github, twitter etc. and I prefer to have a canonical handle defined by the project.

Also note that with a unique top-level file, readable by an out-of-the-box parser (here toml), complexy is vastly reduced compared to our current cascading system. The parser/scanner we have in gordon is pretty hairy and from personal experience, modifying it is non-trivial.

All true, but toml is so ugly! 😄

Maybe we should give it a new name or a standardized toml extension to make it clear that this is not the old format?

+1. I didn’t realize this was a format (new to toml) but I’m glad we’re not building a parser for this.

On Nov 14, 2014, at 3:31 PM, Solomon Hykes notifications@github.com wrote:

In MAINTAINERS:

"docker/project/make"

]

[Subsystem.remote api]

people = [

"vieux"

]

+[people]
+

[people.shykes]

Name = "Solomon Hykes"

Email = "solomon@docker.com"

Github = "shykes"
Also note that with a unique top-level file, readable by an out-of-the-box parser (here toml), complexy is vastly reduced compared to our current cascading system. The parser/scanner we have in gordon is pretty hairy and from personal experience, modifying it is non-trivial.

—
Reply to this email directly or view it on GitHub https://github.com/docker/docker/pull/9137/files#r20394374.

toml is not earth-shatteringly awesome, but I think it's more human-friendly than JSON, less radioactive than YAML, less dusty than INI and easier to parse than unstructured text, so I guess I didn't find anything that sucked less :)

I'm +1 on TOML, and don't understand why you guys are unhappy :P

shykes · 2014-11-14T22:55:33Z

I moved the small, form-only changes to #9177.

shykes · 2014-11-14T23:26:18Z

@jfrazelle @icecrime @tiborvass @fredlf @tianon @erikh @unclejack @vieux @aluzzardi @dmp42 @dmcg @vbatts @vmarmol @SvenDowideit and everyone else currently in a MAINTAINERS file anywhere... Could you please:

Check out this branch
Edit the new top-level MAINTAINERS to add your contact information in the [People] section at the bottom
Open a sub-pr against my pr

While you're at it, you can provide feedback on the rest :)

Thanks!

shykes · 2014-11-14T23:39:18Z

I added inline comments to MAINTAINERS to make it more self-describing. Currently this is pretty redundant with the full documentation at project/MAINTAINERS.md. Maybe that's ok? Thoughts?

tiborvass · 2014-11-14T23:49:26Z

MAINTAINERS

wow i didn't know TOML handled spaces :) (checked online)

shykes · 2014-12-07T19:50:13Z

@dmcgowan yeah it's gitrepo/folder. I renamed registry to docker-registry to be consistent, thanks.

cyphar · 2014-12-16T15:55:14Z

So, to make sure I'm understanding this PR right: Are the maintainer rules are just being formalised (as well as consolidated) in the MAINTAINERS file? I ask because reading through it, the rules look about the same (except now people are being explicitly mentioned, and there's more verbosity about how things should work). Are there any functional changes to the maintainer-ship or contribution processes embedded in this PR? Or is it all refactoring/formalisation/consolidation?

vbatts · 2015-01-13T18:31:52Z

@shykes next steps? and DCO marker? ;-)

Note: this deprecates the fine-grained, high-overlap cascading MAINTAINERS files, and replaces them with a single top-level file, using a new structure: * More coarse grained subsystems with dedicated teams of maintainers * Core maintainers with a better-defined role and a wider scope (if it's not in a subsystem, it's up to the core maintainers to figure it out) * Architects * Operators This is work in progress, the goal is to start a conversation Signed-off-by: Solomon Hykes <solomon@docker.com> Signed-off-by: Erik Hollensbe <github@hollensbe.org> Signed-off-by: Arnaud Porterie <arnaud.porterie@docker.com> Signed-off-by: Tibor Vass <teabee89@gmail.com> Signed-off-by: Victor Vieux <vieux@docker.com> Signed-off-by: Vincent Batts <vbatts@redhat.com>

tiborvass · 2015-01-28T06:58:33Z

MAINTAINERS

vbatts misses comma

icecrime · 2015-01-28T07:01:36Z

MAINTAINERS

It's "lk4d4"!

icecrime · 2015-01-28T07:07:55Z

MAINTAINERS

Something wrong here (truncated word "quali" unrelated to the end of the sentence).

tiborvass · 2015-01-28T07:14:01Z

Overall LGTM :)

icecrime · 2015-01-28T07:19:08Z

Same here, I don't see any remaining issues: LGTM 👍

unclejack · 2015-01-28T07:27:15Z

LGTM

jessfraz · 2015-01-28T07:46:48Z

LGTM

shykes · 2015-01-28T08:20:15Z

Ok, after much discussion on irc, I think we're ready to merge.

Added missing people
Added missing subsystems
Officialized de-facto core maintainers
Removed the vague notion of "lead"
Clarified the roles of Chief Architect, Chief Maintainer, Chief Operator

Even merged, this doesn't end the conversation. The goal is to formalize a structure which is already mostly in place informally. This is a necessary starting point for attacking more ambitious upgrades to the organization.

The big topic which remains to be addressed: how do we transform from a tool-centric organization to a platform-centric organization? Docker is no longer a single tool, but a collection of tools unified under a platform. We want this platform to be composable (each tool should be useful standalone, and replaceable by another), but also well integrated: the user experience should feel like more than the sum of the parts. To achieve this, we need to address integration at many levels. More on this topic soon!

Improve project organization

shykes · 2015-01-28T09:23:17Z

@cyphar it's mostly formalizing what is already in place, but also incorporating de-facto rules that have appeared organically but weren't documented. For example, the concept of "core maintainers" which are the de facto owners of everything which isn't a clearly separated subsystem - that was already the case but not clearly documented. This file also deprecates the more fine-grained MAINTAINERS files - because in practice we were ignoring them often.

The other important change is that I am reducing the role of the bdfl, and creating 3 new leadership roles: Chief Architect, Chief Maintainer, Chief Operator. That should help reduce the dependency on bdfl for running the project, while keeping it as a guarantee for the long-term direction and governance of the project.

shykes changed the title ~~Contribution docs~~ Improve project organization, and document it better Nov 13, 2014

SvenDowideit reviewed Nov 13, 2014
View reviewed changes

MAINTAINERS Outdated

Copy link
Copy Markdown

Contributor

SvenDowideit Nov 13, 2014

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

fredlf :)

ah, ok, references to the [people] huh

crosbymichael reviewed Nov 13, 2014
View reviewed changes

tianon reviewed Nov 13, 2014
View reviewed changes

This was referenced Nov 14, 2014

Rename hack/ to project/devtools (and perhaps others) #3502

Closed

Small improvements to contribution docs #9177

Merged

shykes force-pushed the contribution-docs branch from 1abffc6 to 0426f3d Compare November 14, 2014 23:02

shykes changed the title ~~Improve project organization, and document it better~~ Improve project organization Nov 14, 2014

shykes force-pushed the contribution-docs branch 2 times, most recently from b221abf to af0d801 Compare November 14, 2014 23:23

shykes force-pushed the contribution-docs branch 4 times, most recently from c970fc2 to a9a9694 Compare November 14, 2014 23:38

tiborvass reviewed Nov 14, 2014
View reviewed changes

MAINTAINERS Outdated

Copy link
Copy Markdown

Contributor

tiborvass Nov 14, 2014

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

wow i didn't know TOML handled spaces :) (checked online)

shykes force-pushed the contribution-docs branch from 36e6758 to 517d344 Compare December 7, 2014 19:51

thaJeztah mentioned this pull request Jan 3, 2015

Implement USER setting owner of COPY'd files. #9046

Closed

shykes force-pushed the contribution-docs branch 4 times, most recently from 0fe957b to 4321988 Compare January 28, 2015 06:57

tiborvass reviewed Jan 28, 2015
View reviewed changes

MAINTAINERS Outdated

Copy link
Copy Markdown

Contributor

tiborvass Jan 28, 2015

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

vbatts misses comma

shykes force-pushed the contribution-docs branch from ef89e16 to aa2648f Compare January 28, 2015 07:01

icecrime reviewed Jan 28, 2015
View reviewed changes

MAINTAINERS Outdated

Copy link
Copy Markdown

Contributor

icecrime Jan 28, 2015

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

It's "lk4d4"!

shykes force-pushed the contribution-docs branch 2 times, most recently from 39187a8 to 9ce78e9 Compare January 28, 2015 07:07

icecrime reviewed Jan 28, 2015
View reviewed changes

MAINTAINERS Outdated

Copy link
Copy Markdown

Contributor

icecrime Jan 28, 2015

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Something wrong here (truncated word "quali" unrelated to the end of the sentence).

shykes force-pushed the contribution-docs branch from 9ce78e9 to 33fd281 Compare January 28, 2015 07:08

shykes force-pushed the contribution-docs branch from 33fd281 to 24c9276 Compare January 28, 2015 07:19

shykes force-pushed the contribution-docs branch from 24c9276 to fc11ef6 Compare January 28, 2015 07:22

shykes force-pushed the contribution-docs branch from fc11ef6 to 77f840f Compare January 28, 2015 08:21

shykes pushed a commit that referenced this pull request Jan 28, 2015

Merge pull request #9137 from shykes/contribution-docs

c1f3fe7

Improve project organization

shykes merged commit c1f3fe7 into moby:master Jan 28, 2015

SvenDowideit mentioned this pull request Feb 9, 2015

examine docs PRs to merge into 1.5.0 bump branch #10649

Closed

SvenDowideit mentioned this pull request Feb 26, 2015

possible PRs to merge for a docs-update #11031

Closed

Conversation

shykes commented Nov 13, 2014

Uh oh!

Choose a reason for hiding this comment

Uh oh!

crosbymichael commented Nov 13, 2014

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

jessfraz commented Nov 13, 2014

Uh oh!

shykes commented Nov 13, 2014

Uh oh!

tianon commented Nov 13, 2014

Uh oh!

tianon commented Nov 13, 2014

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

shykes commented Nov 14, 2014

Uh oh!

shykes commented Nov 14, 2014

Uh oh!

shykes commented Nov 14, 2014

Uh oh!

Choose a reason for hiding this comment

Uh oh!

shykes commented Dec 7, 2014

Uh oh!

cyphar commented Dec 16, 2014

Uh oh!

vbatts commented Jan 13, 2015

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

tiborvass commented Jan 28, 2015

Uh oh!

icecrime commented Jan 28, 2015

Uh oh!

unclejack commented Jan 28, 2015

Uh oh!

jessfraz commented Jan 28, 2015

Uh oh!

shykes commented Jan 28, 2015

Uh oh!

shykes commented Jan 28, 2015

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

20 participants