Issue structure #71
Issue structure #71
Conversation
| The Inclusivity Working Group exists to increase inclusivity and diversity within the Node.js collaborator base. These discussions often touch on a wide range of topics which makes it easy for discussions to get off topic. The following requirements exist for filing issues to help make sure discussions stay on topic. | ||
|
|
||
| - Issues should be filed with the intention of actionable steps being taken to further the mission of this working group | ||
| - Issues in this repository are not the place for, e.g., individual education about inclusivity/diversity or discussing whether or not this group should exist. |
There was a problem hiding this comment.
The use of e.g. doesn't make sense here, it should just be removed.
There was a problem hiding this comment.
If it should be kept, it should be replaced with for example rather than e.g..
|
Thanks for the feedback, good points all around. I reworded some of the sentences that used |
ashleygwilliams
added
work in progress
agenda-item
and removed
operations
question
labels
|
|
||
| The purpose should be a brief description of what you would like to see addressed. The type of issue should be explicitly mentioned in the purpose: | ||
|
|
||
| - _Question_ Some of the policies and recommendations of this group may not be clear, and a question asks for clarification. The resolution to a question should be an answer in the issue, not a change to policy or documentation. This issue may lead to the filing of a new request for changes issue. |
There was a problem hiding this comment.
Are we sure another issue is necessary if something ends up needing to clarified in the documentation?
Having a second issue required seems like it may be counterproductive. Also, we can always rename the issue to clarify what it actually asks.
There was a problem hiding this comment.
Good call. I'll reword to say that issue authors can file a new issue, or rename the original, at their discretion
|
The bottom of the document sounds like a template but it's not that clear about that. Could we add an example at the bottom within code blocks to show the markdown (and be copyable)? |
nebrius
force-pushed
the
issue_structure
branch
from
746a1b3 to
fb42848
Compare
|
I added some examples, PTAL. I also rebased against master to fix merge conflicts. |
| Even though we have a charter, this WG is essentially still in its early | ||
| stages. | ||
| If you are interested in helping shape this WG, have a look at the issues and PRs. | ||
| Even though we have a charter, this WG is essentially still in its early stages. If you are interested in helping shape this WG, please have a look at the issues and PRs. | ||
|
|
||
| _TODO: Add starting points_ |
There was a problem hiding this comment.
What's a starting point in this context? Do you mean a list of linkable contents?
There was a problem hiding this comment.
This wording is old and being replaced in #88. TBH I'm not exactly sure what a starting point is either :)
|
Looks great to me. Having a contents section to get to the bits of the doc you want would be great, but that might be what is meant by 'starting point' and will likely be completed once the doc itself has been okay'ed. Thanks @nebrius, this is really cool. |
|
|
||
| Here is an example for a question issue: | ||
|
|
||
| ``` |
There was a problem hiding this comment.
code blocks don't respect soft wrap so this is a bit difficult to read, consider hard wrapping at 80cols, or probably easier/better, just use > and quote it instead of using a code block.
this is an amazing example. are you familiar with the grilled cheese copy pasta? https://www.reddit.com/r/copypasta/comments/2os2lp/its_about_ethics_in_grilled_cheese_sandwich_making/
There was a problem hiding this comment.
👍 for using > to block quote
There was a problem hiding this comment.
omg that link is amazing @ashleygwilliams!!!
Unfortunately, doing > ## Title renders as
Title
so it can't be copy pasted. I can do 80col hard wraps though.
|
this is awesome and a great start. i wonder if this should be a document on it's own called "policy issues" linked to from the contributing.. i'm a fan of small documents that are all grouped together with a ToC. the primary info in contributing should be where to start so maybe an explanation of who we are, what to read, and then links to how to contribute policy changes, and also how to submit an idea for a new program. thoughts? |
| - Are hot dogs considered to be an American invention, or are they also considered of German origin? | ||
| ``` | ||
|
|
||
| Here is an example for a request for changes to a policy issue: |
There was a problem hiding this comment.
same as above re: "for"/"of" and making it clear that it's a type example from above
|
ok, done with my review! ✨ |
|
Thanks everyone for the reviews, I know this one is a little denser than most :) I think I addressed everyone's concerns, PTAL! |
|
|
||
| - _Question_ A question about any of the policies, programs, processes, etc of this Working Group. Some of the policies and recommendations of this group may not be clear, and a question asks for clarification. The resolution to a question should be an answer in the issue, not a change to policy or documentation. | ||
| - _Request for changes to a policy_ A request for change is used to clarify an existing policy. Issues of this type are typically of the form "This document is unclear in the case of x. Can we modify it to be more explicit?" or "The document says x, but I think it would be more effective if we did y instead". | ||
| - _Request for new policy_ This Working Group's equivalent of a feature request, a request to create new policies. |
There was a problem hiding this comment.
@ashleygwilliams mentioned something about 'Request for a new program', if we can get an idea of what that should look like, would it be a good thing to mention here as a bullet point too?
|
Here is a magic URL I made to show how we could help people make 'Question' issues click |
|
@Charlotteis those URLs are totally going to come in handy, thank you :) |
|
@nebrius this still needs to be moved out of |
D'oh! Last run through I only read the inline comments, sorry! 😅
I love the magic link idea! Is it better to have the example pasted in (which users have a reference too but have to delete), or to have more of a template (with placeholders such as "fill in purpose here") and have the magic links right above the example in POLICY_ISSUES.md that they can refer back to? |
|
Regarding programs, I kinda feel like it might help to get some of the basics for programs down first before setting up issue guidelines (what do they look like, what is the process like for getting new programs going, etc), in the form of new policies, but what does everyone else think? |
|
ok, I tweaked the intro wording to hopefully make it more friendly and approachable, and I moved everything into docs/POLICY_ISSUES.md. I still would like to get clarification on programs, so let's not consider this ready to merge yet. Also, @beaugunderson I responded to some of your questions inline in the diff, and since pushed changes that marked those as "commented on an outdated diff". When you get a chance, can you let me know what you think? |
|
if we do get one of these magic URLs (which i'm absolutely for), then let's also put it somewhere in
if, hypothetically, someone were to create an issue from scratch, they might be clicking the link to review the contributing guide, which is where they might also see the new magic URL. tl;dr: put the magic link in CONTRIBUTING.md, it helps guide issue creators the right way |
|
@nebrius just responded to the one thing that i hadn't responded to that was still an open question, i think :) |
Probably better to have 'fill purpose here' unless we want people to delete several paragraphs about hot dogs every time they open an issue :) |
|
a++ i think this is good to merge. we can continue to iterate, but this is an great start and @Charlotteis already used it which is awesome. thoughts? |
|
Let me get the magic links included in the doc, rebase, and then I think we're good to go! I'm thinking we can wait on magic links in CONTRIBUTING.md for now cause of #88. |
|
fine by me, i'll open a separate PR when it's time |
nebrius
force-pushed
the
issue_structure
branch
from
9232256 to
a22c92a
Compare
|
LGTM! 😎 |
|
wooo, merging. awesome job for spearheading this @nebrius -- and thanks to everyone for participating so thoughtfully! |
A proposal for what we want issues to look like for this repo and an effort to help keep discussions on topic.