WIP: Initial work on Project Lifecycle. #332
There are no files selected for viewing
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -0,0 +1,101 @@ | ||
| # Protocol Labs Project Lifecycle | ||
|
|
||
| * Outline | ||
| * Active States | ||
| * L0: Prototype | ||
| * L1: “In Org” | ||
| * L2: Contributors Welcome! | ||
| * L3: Growth | ||
| * L4: Top Project | ||
| * L5: Flagship Project | ||
| * Inactive States | ||
| * D0: Actively Maintained | ||
| * D1: Critical Fixes Only | ||
| * D2: Hard Deprecated | ||
|
|
||
| ## Lifecycles and API Stability | ||
|
|
||
| For the most part, a project’s place in the lifecycle does not describe it’s API stability. | ||
| API stability is required once enough people depend on that API and can’t always be planned for. | ||
|
|
||
| However, it is assumed that once a project reaches L3 the project is actively soliciting | ||
| users and is dedicated to supporting them by not breaking API unless absolutely necessary. | ||
| Similarly, API changes should not happen in inactive states as we are no longer soliciting | ||
| users and are only investing to the extent that people already depend on them. | ||
|
|
||
| ## L0: Prototype | ||
|
|
||
| *Examples: proto.school* | ||
|
|
||
| During the initial stages of development projects exist either on developer’s personal GitHub | ||
| accounts or in specific orgs like shipyard that are intended to house experimental development | ||
| and demo’s. | ||
|
|
||
| At this stage, attention is a liability, and providing a nice website, good documentation, | ||
| or other promotion would only bring unwanted attention too early. | ||
|
|
||
| ## L1: “In Org” | ||
|
|
||
| *Examples: interface-ipld* | ||
|
|
||
| When projects are moving into relevant PL orgs they are expected to have: | ||
|
|
||
| * Guaranteed test coverage at a reasonable level. | ||
| * TBD: other automation. | ||
|
|
||
| ## L2: Contributors Welcome! | ||
|
|
||
| *Examples: peerpad* | ||
|
|
||
| At this stage the project is ready to solicit additional contributors from | ||
| the community. It should expect. | ||
|
There was a problem hiding this comment. I think ”users (or people) should expect” might be better phrasing here. There was a problem hiding this comment. Hrm... maybe we should have two sections at this point. On the one hand, I want to note what project engineers should expect in terms of support from the rest of the org. Additionally, at this point users should also have expectations. |
||
|
|
||
| * Occasional features in the newsletter and in social media. | ||
|
There was a problem hiding this comment. Are you planning to revive https://github.com/ipfs/newsletter, or are you thinking of something different here? There was a problem hiding this comment. Yes, we're in discussions to do a monthly newsletter :) |
||
| * Community Engineering Support: | ||
| * Issue Triage and cleanliness | ||
| * TBD: other automation. | ||
|
There was a problem hiding this comment. What level of stability, activity, and focus should contributors and users expect here?
There was a problem hiding this comment. I want to stay away from making API stability guarantees in the leveling. Different projects will have different requirements around this. For the most part, I think that stability should be dictated by the downstream users. The more people depend on something the more effort we have to make to not break them. No leveling or proposed planning for stability can change how many depend on a project. There was a problem hiding this comment.
Totally true! I’m more trying to get at what commitments or non-commitments people should expect at a minimum of a project at this level. I guess I was feeling like it’s useful to be clear that L2 is still a fuzzy stage for a project so we explicitly don’t guarantee much stability (whether a project does or doesn’t have more stability in practice is a different story, as you say). There was a problem hiding this comment. I think that individual projects needs to decide what their API stability policies are. I don't think this is something we can generalize sufficiently in the leveling. One big issue is that the needs you have in API stability change dramatically based on how you consume dependencies, so package managers and modules system make a big difference. It's entirely possible that big API changes are acceptable even at stable points in the cycle for certain projects. However, to your point, I think that we should make it clear that at L0 we make NO guarantees. |
||
|
|
||
| ## L3: Growth | ||
|
|
||
| *Examples: dag-cbor, js-libp2p* | ||
|
|
||
| At this stage the project is ready to solicit many more users and dependents than it currently has. | ||
| It should expect: | ||
|
|
||
| * Frequent features in the newsletter and in social media. | ||
| * Featured talks and videos in YouTube channel. | ||
| * Content Creation: workshops, tutorials, documentation, conference talks. | ||
|
There was a problem hiding this comment. You said it a little at the top, but we should repeat here:
There was a problem hiding this comment. Not all languages have adopted semantic versioning so I wouldn't want to lay that down as such a broad rule. In terms of API stability, see prior comments on API stability :) There was a problem hiding this comment.
I totally understand not having anything specific to say in L2 (per your prior comment), but you’ve already made a broad, L3-level statement about stability at the top of the doc (“However, it is assumed that once a project reaches L3 the project is actively soliciting users and is dedicated to supporting them by not breaking API unless absolutely necessary”). That seems worth restating here so when people inevitably breeze past the descriptive intro, it’s still listed in this part, where people are looking for actual requirements/expectations. |
||
|
|
||
| ## L4: Top Project | ||
|
|
||
| *Example: js-ipfs, go-ipfs* | ||
|
|
||
| At this stage the project has reached a level of maturity in users and community that we feature it often. | ||
|
|
||
| * Frequent talks and workshops at our events. | ||
| * Featured spot in the GitHub org (if available). | ||
|
|
||
| ## L5: Flagship Project | ||
|
|
||
| *Examples: libp2p, IPFS, IPLD* | ||
|
|
||
| Most project repositories do not reach this point. This status is reserved for broader “project” contexts. | ||
| Projects should expect: | ||
|
|
||
| * Fancy website | ||
| * Dedicated social media accounts | ||
|
|
||
| ## D0: Actively Maintained | ||
|
|
||
| *Examples: dag-protobuf* | ||
|
|
||
| This status is for libraries we still maintain and possibly even rely on but have already made a strategic | ||
| decision to move away from. | ||
|
There was a problem hiding this comment. Do the types of things in ipfs-inactive/docs#54 come in here or in D1? (Or some here and some in D1 or D2, like archiving on GitHub?) There was a problem hiding this comment. Those sound like D1 or D2. There was a problem hiding this comment. Ahhhhhh, I see, so D0 isn’t deprecated, it’s more about intent to deprecate. There was a problem hiding this comment. I guess I had some confusion here because UnixFS v1 & dag-protobuf are currently more than just maintained; they get active changes and improvements, so the name (“actively maintained”) made think this was more of a state those libraries would move into in the future. There was a problem hiding this comment. Correct. The roots of this lifecycle go all the way back to when I saw a table of IPLD implementations that noted |
||
|
|
||
| ## D1: Critical Fixes Only | ||
|
|
||
| We’ve deprecated our own use to the extent that we can and encourage the community to do the same. | ||
|
There was a problem hiding this comment. Does this specifically mean there should be an alternative solution or approach to whatever the project was meant to do? (e.g. dag-protobuf might move here only when UnixFS v2 is shipping and on by default in IPFS.) There was a problem hiding this comment. Correct, we should always be able to point to docs for new things that satisfy these use cases. There's lots of future cases for this, we have GraphSync eventually replacing Bitswap for instance. There was a problem hiding this comment.
Can we say here that we will recommend better alternative tools or approaches? :) There was a problem hiding this comment. Yes, I'll add that in. |
||
|
|
||
| ## D2: Hard Deprecated | ||
|
|
||
| Using this library is actively harmful. | ||
|
There was a problem hiding this comment. Guessing no, since D1 is “critical fixes only,” but do we make any guarantees about maintenance or security fixes? Would be good to clearly spell out any guarantees we make here (or that we don’t make any). There was a problem hiding this comment. At this point we don't make any changes ever. It's rare to deprecate something to this point unless the project's design causes security concerns or if the underlying dependencies (like crypto) have known vulnerabilities that aren't being fixed. This happens a lot when a project is tightly bound to a version of OpenSSL, you can't update it without breaking ABI and the version it is binding to is no longer maintained by OpenSSL. |
||
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
Does L1 explicitly indicate that PL is dedicated to supporting the project going forward? I’m thinking about the confusion brought about by repos like ipfs-mans or ipfs-nodeschool, where there were only a few commits on a single day and no further effort.
There are lots of repos like this, and I have heard feedback about frustration from this by users, so one thing I’d love to see clarified in these descriptions is a level of commitment.
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
Also, are there implications on licensing here? What if someone starts something as a personal project in their own account, but it moves to the IPFS org — does the license need to be reassigned to PL, or do we expect that some “in org” projects have individual copyright?
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
Also also, do we make some guarantees about READMEs and descriptions at this point? (or is that L2?) I’m thinking of ipfs-inactive/docs#55.
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
We're supporting it while it is L1 or higher but it could still be moved to D0 and we'd move away from it.
Those are probably L0. They look like prototypes we built and then let go of. This will happen a lot, and that's why there is a level for them where they aren't in main orgs or messaged as being supported.
There's two terms we need to be clear about: copyright ownership and copyright license.
For the most part, people own their contributions. Companies can own contributions they've paid for but it's actually quite rare that a company will transfer ownership from an individual to the company, mostly because certain countries (Germany) just don't recognize a complete transfer of intellectual property.
A license is the rights non-owners are granted to the property. Public licenses grant the public rights to the work. For the most part, we only need to care that the work is licensed under a good public licenses (which ones we use/recommend is a longer conversation). We don't need to own the copyright. We may need to own the trademark if there is one, but that's a totally different legal structure than copyright which would take a long time to discuss :)
That's up for discussion. The important thing here is that L1 needs consistent tooling/docs to make it useful within the project and L2 needs consistent tooling/docs for it to be useful to people outside the project.
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
Awesome. I feel like it might be worth stating that explicitly, e.g.
* Commitment to support and grow this project going forward and, if that changes by moving to D0/D1/D2, we’ll make that explicitly clear.Maybe worth noting this as a descriptive point? e.g.
Being a repo in one of the main orgs signals L1+ status, so most projects should not start there. We haven’t done that well in past, but part of the goal with this plan is to change that.Yes! Sorry, I should have written “does the copyright line in the license need to be reassigned.” But you answered that question anyway :)
I think it is worth making this a clear point in the doc, e.g. “L1+ projects must have a public, open source (?) license.” Seems reasonable not to specify exactly which licenses are ok here — we’ve had long discussions and have a policy on what licenses should be used for original PL projects, but agree that projects coming from elsewhere/other people might not use that specific set of licenses, and that’s ok.
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
Probably a good idea, but I want to hear what @diasdavid has to say about the lifecycle before I sign us up for such a big shift in policy.
This probably needs to go in another document, and to some extent I think is already documented elsewhere, and we can link here. We also require the DCO and signoff signatures in commits. There's a ton of rules for being "in org" we need to tighten up. For now, I'm going to say that it's out of scope for this doc and find something to link to that we can iterate on later.