WIP: Initial work on Project Lifecycle. #332
Conversation
ghost
assigned 
|
LGTM. This seems reasonable to me. I like that it would communicate more clearly with the community what we think the state of a project is and what their expectations should be. |
|
@diasdavid @jbenet @flyingzumwalt @Mr0grog any thoughts on this? |
| When projects are moving into relevant PL orgs they are expected to have: | ||
|
|
||
| * Guaranteed test coverage at a reasonable level. | ||
| * TBD: other automation. |
There was a problem hiding this comment.
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.
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.
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.
Does L1 explicitly indicate that PL is dedicated to supporting the project going forward?
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.
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.
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.
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'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 :)
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.
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.
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.
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.
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.
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.
There's two terms we need to be clear about: copyright ownership and copyright license.
Yes! Sorry, I should have written “does the copyright line in the license need to be reassigned.” But you answered that question anyway :)
we only need to care that the work is licensed under a good public licenses (which ones we use/recommend is a longer conversation)
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.
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.
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.
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.
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.
| At this stage the project is ready to solicit additional contributors from | ||
| the community. It should expect. | ||
|
|
||
| * 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 :)
| * Occasional features in the newsletter and in social media. | ||
| * 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?
- Frequent API changes?
- Minimal documentation?
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.
No leveling or proposed planning for stability can change how many depend on a project.
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.
| *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.
|
|
||
| * 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:
- A relatively stable API (semantic versioning?)
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.
In terms of API stability, see prior comments on API stability
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.
|
|
||
| ## 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.
we should always be able to point to docs for new things that satisfy these use cases
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.
| *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. dag-pb is the primary use case for D0. We are still using it, actively, in IPFS but we know we want to stop in the future. All new features are being planned on dag-cbor or to be for a somewhat agnostic format that new dags support but dag-pb doesn't. We need to stop pointing to the docs and stop pushing people down a path that uses the library but it isn't in any real sense "deprecated" because we're still using and actively developing it.
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 dag-pb as being "deprecated" which was incredibly confusing because we were still using it everywhere and it's still the default.
|
Any blockers left to merge this? |
|
I like the proposal and there was no negative feedback and it is sad it stayed open here. My only questions is what to do with it once merged. Should we edit readme's in all repos to include the level? Or add a badge? What was the original idea? |
This is a proposal to bring some alignment to what stage of maturity each project repository is at so that support services (community engineering, evangelism, comms, events, etc) can understand what level of support they should be providing in each case.
It is unclear how widely this lifecycle should be messaged so this proposal focuses on describing each point in the lifecycle strictly in terms of what support should be provided to projects at each point.
This isn't IPFS specific but this repo seems like the right place to have the discussion.
This is still an early draft, feedback is incredibly welcome. I'd like to know what other services people would like to see at different points in the lifecycle, other examples, etc.