Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Edit to technical values document #34

Closed
3 of 7 tasks
mmarchini opened this issue Nov 12, 2020 · 8 comments
Closed
3 of 7 tasks

Edit to technical values document #34

mmarchini opened this issue Nov 12, 2020 · 8 comments

Comments

@mmarchini
Copy link
Contributor

mmarchini commented Nov 12, 2020

  • Add text about revisiting the values frequently (each year?)
  • Should we have rules/guidelines to how changes to the doc should land? For example, does it require TSC approval (similar to collaborator guide changes and semver major)?
  • Add section about how the document should be interpreted, and how ambiguity should be handled
  • Add text explaining it is a living doc
  • More line items
  • Clarify if the current doc reflects the current state of the project or what we envision that the technical values should be
  • Should we remove the priorities?

(living issue, will keep writing on it until the meeting is over)

@boneskull
Copy link

some reflections on this document (some of which have already been mentioned):

I do not understand the goal of the document. Is it to:

  • Document the project's values as they currently stand?
  • Document the project's values as they should stand?
  • Serve as a decision-making guide?

Say every single active contributor reviewed this document and approved it. Given the disparate values and opinions found amongst the contributor base, have we actually said anything here? If the document is so vague that no X is of higher priority than any Y, then it cannot serve as a decision-making guide... because it provides no real guidance.

Yet, if we have a numbered list in order of priority, and we needed contributor approval to "land" the document, I imagine it'd come to a TSC vote. Further, a TSC vote either way is unlikely to make an impact on the values or opinions of any objecting contributor.

To @MylesBorins's comment during the meeting today...

Maybe what I want to see is a "constitution"--a document that is explicit about the project's values and clearly favors some over others. Maybe that document is difficult to change outright, but not impossible to amend. Maybe that would attract contributors who share Node.js' values and discourage contribution by those who do not. I see that as a positive, and a project where it would not be nearly as difficult to make a major impact as it is today. Perhaps... such a document needn't be "ratified" by the contributor base at all, but rather only the TSC, since it's empowered to have the final say in all decisions.

But... maybe you disagree. 😝

Regarding the TSC, I'd very much wish to see explicit support (maybe that's "signed by" each) for the Grand Enumeration of Node.js Values. I would feel more confident that this document actually means something.

@GeoffreyBooth
Copy link
Member

I do not understand the goal of the document.

In my mind, it is to document the project’s values in order to serve as a decision-making guide. We’re not doing this as a journalistic or marketing exercise. If we have a statement of principles that the broader project has agreed upon, then when smaller groups get into debates they have something to refer to that could help point them in the direction that the broader project would hope that they go in.

And as for “currently stand” versus “should stand,” this should represent how they should stand. If the document represents how the values currently stand, but we wish the values were otherwise, then it would function as an explanation for past decisions but not as a guide for helping make future ones.

@boneskull
Copy link

If we have a statement of principles that the broader project has agreed upon, then when smaller groups get into debates they have something to refer to that could help point them in the direction that the broader project would hope that they go in.

OK, thanks. IMO, an unordered list of "things to consider when making decisions" is going to be a poor helper. At most, it would illustrate the relative unimportance of that which was omitted from the list.

But maybe a priority-free list is all we can reasonably expect to get contributors to agree upon. 🤷‍♂️

@boneskull
Copy link

Another (potentially bad) idea: Instead of a list, a table with two columns, A and B. When faced with a tradeoff, we prefer picking from column A instead of column B. e.g:

Prefer... ...over
Convention Configuration

@GeoffreyBooth
Copy link
Member

Instead of a list, a table with two columns

That’s just another way of prioritizing. Personally I don’t mind the priority levels, I think that’s kind of the point: to show which values should (generally) take precedence over others.

@mhdawson
Copy link
Member

Opened this to add some context in the doc: nodejs/node#36201

I personally also think we should stick with the priority levels. We went into the discussion thinking it might be hard to agree, but it turned out to be relatively easy when we went through the exercise. I'm thinking we leave as is until it causes an issue.

@mhdawson
Copy link
Member

mhdawson commented Jan 6, 2021

I think nodejs/node#36201 which has landed covered:

Add section about how the document should be interpreted, and how ambiguity should be handled
Add text explaining it is a living doc
Clarify if the current doc reflects the current state of the project or what we envision that the technical values should be

@mhdawson
Copy link
Member

It's been over 2 years since we had discussion on this, I'm going to close. Please re-open if you feel that was not the right thing to do.

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Labels
None yet
Projects
None yet
Development

No branches or pull requests

4 participants