Draft of /social/process/how standard #2
Conversation
Co-authored-by: mattyg <[email protected]>
| @@ -0,0 +1,30 @@ | |||
| --- | |||
| HOW: <path in HOW tree> | |||
There was a problem hiding this comment.
Rust suggests acronyms should not be all caps, so Json. Should this be How?
There was a problem hiding this comment.
Well, I tried this out, but there are so many places in the the doc that refer to "a HOW" and if you pluralize it makes more sense as "HOWs" than "Hows". And I've never seen an RFC or an EIP written as an Rfc or Eip. So I'm not so sure about this even if we go with something other than HOW.
HOW/social/process/how/how-v1.md
Outdated
| #### Refine | ||
| This is the review stage, when Author(s) are ready for feedback from the core developers and the community at large. The status for this stage are: `REVIEW`, `LAST CALL`. The steps in this stage are: | ||
|
|
||
| 1. A member of the core team or requested working group will do an initial evaluation of the PR. If the a team member of working group member is willing to take on stewardship of this HOW they will update the header status to `REVIEW` and will add the section(s) specified in `/social/process/how/_requirements.md#Process Template Section: REVIEW`. If no requested steward is willing take on the HOW it MUST be updated to status `REJECTED` and the section(s) specified in `/social/process/how/_requirements.md#Process Template Section: REJECTED` added. |
There was a problem hiding this comment.
I don't understand the point of setting it to rejected. I assume we don't want to merge every spammy pr that may be opened filling our directory structure with rejections. Shouldn't we just close the PR?
There was a problem hiding this comment.
So, this certainly makes sense for spam and other things that are cursorily rejected because they don't actually get taken up by the team, or a working-group or some steward to consider. But if there were taken up and considered at length, and especially if there's some formal process to say "nope we actually don't want to do this", it seems like it's worth holding on to that information inside the HOW process not just in github close PR comment.
But maybe we could have that also fall under the ABANDONDED status with a Reason that would be "Formally rejected" for that case?
HOW/info/README.md
Outdated
| # Informational Documents | ||
| Information about Holochain design issues, or general guidelines or information to the Holochain community. These documents aren't technical or social standards, but are useful information that has been aligned on through the HOW process. |
There was a problem hiding this comment.
I can't fathom what this might be. Maybe add an example? Or remove this info-type until a real need for it arises?
There was a problem hiding this comment.
So for me this would be a place where we might put explanatory texts that define terms that are being used in the context, exactly like what we were talking about in our meeting around Privacy/Security/Secrecy.
I'm not wed to this, could remove for the sake of simplicity.
There was a problem hiding this comment.
I'm good either way, just need an example in the text if you'd like to keep it : )
There was a problem hiding this comment.
Same for me, without an example or more specificity this is too abstract for me to grasp.
There was a problem hiding this comment.
So here's an example from the IETF: https://www.rfc-editor.org/rfc/rfc4677
In the RCF process they have an "Informational" designation:
An "Informational" specification is published for the general information of the Internet community, and does not represent an Internet community consensus or recommendation. The Informational designation is intended to provide for the timely publication of a very broad range of responsible informational documents from many sources, subject only to editorial considerations and to verification that there has been adequate coordination with the standards process (see section 4.2.3).
This is where this comes from. I will add something to the description to make it less abstract.
| 1. merging the `_requirements.md` files that live at each level of the tree including and above the leaf where the HOW is being added | ||
| 2. merging in any additional body sections or headers specified by a status change in a process flow template. |
There was a problem hiding this comment.
Merging is a cute thought, but adds friction to understanding what is needed to contribute. Perhaps the _requirements.md should be true templates that live at the leaves, even if that means duplicating a little bit?
There was a problem hiding this comment.
Yeah, in the pull request description I mention the idea of having a script that does that merging into a _templates.md file, and I had imagined that that file would live alongside the requirements at each step of the hierarchy so that you could see what's required at any point. I guess I was just worried about "source of truth" but I think it's worth doing this to reduce friction.
There was a problem hiding this comment.
Some suggestions and questions, but looks pretty good to me. Not sure if it'll be too much overhead before experiencing the process a couple times.
More general question: Is there any suggestion / guidance for getting things that are already designed/implemented in here? Or are we starting from now with no history?
typos fixed from review Co-authored-by: David Braden <[email protected]>
|
|
||
| ## Motivation | ||
|
|
||
| Clearly explain why this standard is being proposed. If the standard is a new version of an existing standard, or makes one SUPERSEDED explain why that is inadequate to address the problem that this HOW solves. Include specific use cases and describe why this HOW is valuable to the Holochain ecosystem. |
There was a problem hiding this comment.
that this HOW solves
What does HOW stand for? Should this read `Holochain proposal" or something like that?
There was a problem hiding this comment.
It currently doesn't stand for anything. A few ideas have been tossed out (I like Holochain Organized Wisdom). I would prefer to pick something for it to stand for than to have it stand for nothing.
There was a problem hiding this comment.
I agree. I'd rather change it to something common in the software engineering industry than using a term (that's also a common word like "how") that we need to invent a meaning for.
There was a problem hiding this comment.
In the top level README I describe it as:
This repo contains and embodies the standards and processes for the documentation and evolution of the Holochain Framework and Ecosystem, in other words, how we come into alignment. (If you want HOW to be an acronym it could be Holochain Organizational Work, or Holochain Ongoing Wishes, or Holochain Organized Wisdom, or the recursive How Organizing Works)
For me, I like some level of playfulness as part of our organizational DNA. But if this feels like too much I'm willing to convene the department of names department...
|
|
||
| ### <status> Reason | ||
|
|
||
| The reason this standard was not accepted or was superseded. In the case of superseding, the content of this section MUST include which HOW, or HOW version makes this HOW obsolete. |
There was a problem hiding this comment.
I'd question this in the SUPERSEDED case. Without building your own UI client or diffing tool, it's not that easy to see whether something other than the status reason changed.
As a user, I'd want to know that I'm reading the same text that was written when the proposal was accepted or rejected.
I think this should be metadata managed by the app and not part of the document content itself. I'd actually like the app application's code to enforce that an accepted proposal never changes again.
There was a problem hiding this comment.
metadata managed by the app
The idea is that HOWs are a github-native process for now. When we and holochain are ready it can be migrated to a happ.
There was a problem hiding this comment.
Yeah, I agree that when we get to this in the App it shouldn't be in the final document, but at least for now because it's git, you would know to look at a previous commit to find the previous value.
| As Holochain and the Holochain ecosystems evolves, we want a standardized process for proposing, adopting, and documenting standards of all types, including: protocol creation and changes, feature additions, and process improvements, etc. A well-defined HOW process helps: | ||
| - Maintain transparency in decision-making | ||
| - Ensure proper technical documentation | ||
| - Foster community participation |
There was a problem hiding this comment.
This concerns me. We really don't have the tooling in place in Holochain to make this a resilient space to host content. If somebody decides to engage negatively or just flood in comments then we have limited options for dealing with it.
I suggest that we need to create a separate document for discussion that describes how we operate How. Not a proposal but just a technical guide for ourselves. Like what we do with always-online nodes and backups.
There was a problem hiding this comment.
The idea is that HOW is a github-only process for now. When we and holochain are ready it can be migrated to a happ.
There was a problem hiding this comment.
Yes, the idea is to be able to start doing the process now using before we have matured the hApp.
| @@ -0,0 +1,34 @@ | |||
| --- | |||
| Status: <DRAFT|REVIEW|REJECTED|SUPERSEDED|DEFERRED|LIVE> | |||
There was a problem hiding this comment.
What happened to Holochain Improvement Proposals?
If we used that term then I'd like to propose that we rename "superseded" to "replaced" so that we can have "HIP replacements" :)
There was a problem hiding this comment.
@zippy preferred the term "how" and I don't feel strongly.
| This is the review stage, when Author(s) are ready for feedback from the core developers and the community at large. The status for this stage are: `REVIEW`, `LAST CALL`. The steps in this stage are: | ||
|
|
||
| 1. A member of the core team or requested working group will do an initial evaluation of the PR. If the a team member of working group member is willing to take on stewardship of this HOW they will update the header status to `REVIEW` and will add the section(s) specified in `/social/process/how/_requirements.md#Process Template Section: REVIEW`. If no requested steward is willing take on the HOW it MUST be updated to status `REJECTED` and the section(s) specified in `/social/process/how/_requirements.md#Process Template Section: REJECTED` added. | ||
| 2. Community members make comments and suggested changes on the pull request. |
There was a problem hiding this comment.
I'm a bit concerned that having the discussion directly on the PR makes it really unwieldy to follow if multiple topics need to be discussed in parallel as it is just a linear stream of comments.
There was a problem hiding this comment.
I personally feel that PR comment threads are a good UX for supporting multiple parallel conversations. This comment for example is parallel discussion to other comment threads above and I get notifications if I participated in a thread. Do you have some idea for alternatives?
|
|
||
| state Align { | ||
| REJECTED | ||
| ALIVE |
There was a problem hiding this comment.
Does ALIVE also include actual implementation for holochain core standards? For app-level standards I guess ALIVE is if we agreed on it but for holochain core standards it's not really alive until it's actually implemented in code. But implementation is still considered as part of the ALIGN stage maybe? And what about different versions of holochain? A core standard may be implemented in Holochain version 2.0 but not in version 1.0...
There was a problem hiding this comment.
Hmm that's a good catch. We should track that a core proposal has actually been implemented and at what holochain version.
For now though, since we're starting with HOW only including app-level tech standards, I'd be fine with tabling it.
There was a problem hiding this comment.
On the question of implementation:
My intention was that different types of standards would need different degrees thoroughness in speccing/prototyping/implementation to be considered alive. For example in the IETF/RFC world I believe some standards aren't accepted until there are at least two separate implementations that prove out the workability of the proposal. So I was assuming that we would end up choosing different versions of the alignment process for different standards and that would be specified there.
But I understand that LIVE makes it sound like the standard is actively in use in some code. So I think I will propose changing the LIVE status to just ACCEPTED (which pairs better with REJECTED anyways).
As to versions, I don't think the status itself needs to incorporate version numbers, I think it's more like the documentation of the Holochain (or other libraries and tools) would indicate which standards (and versions thereof) they are using.
Co-authored-by: matthme <[email protected]>
HOW/info/README.md
Outdated
| # Informational Documents | ||
| Information about Holochain design issues, or general guidelines or information to the Holochain community. These documents aren't technical or social standards, but are useful information that has been aligned on through the HOW process. |
There was a problem hiding this comment.
Same for me, without an example or more specificity this is too abstract for me to grasp.
|
|
||
| ## Motivation | ||
|
|
||
| Clearly explain why this standard is being proposed. If the standard is a new version of an existing standard, or makes one SUPERSEDED explain why that is inadequate to address the problem that this HOW solves. Include specific use cases and describe why this HOW is valuable to the Holochain ecosystem. |
There was a problem hiding this comment.
I agree. I'd rather change it to something common in the software engineering industry than using a term (that's also a common word like "how") that we need to invent a meaning for.
| - **REVIEW**: Accepted for peer review by a steward | ||
| - **LAST CALL**: Final review period (14 days) | ||
| - **LIVE**: Approved and adopted | ||
| - **REJECTED**: Not accepted |
There was a problem hiding this comment.
?
| - **REJECTED**: Not accepted | |
| - **REJECTED**: Not accepted or decommissioned |
Draft HOW Pull Request
Path: /HOW/social/process/how/how-v1.md
Description
This HOW adds the default HOW process standard and sets up the HOW directory structure to follow that process.
Considerations for Review
Draft How PRTemplate referenced in the HOW specification._template.mdwhich is a merge operation of all the_requirements.mdup the tree.HOWdirectory and consider the root of the repo the root, and make the README at the top level conform to theREADMEformat that is supposed to live at each level.Stewardship Request
Currently there is no official "Holochain Foundation Structure" working group, though I consider my work with Madelynn to be that. If the working group structure were actually in place I think that would be the group to ask for stewardship from. In the mean-time, I nominate myself as steward of this HOW!