Issue structure

[nebrius]

A proposal for what we want issues to look like for this repo and an effort to help keep discussions on topic.

[nebrius]

Thanks for the feedback, good points all around. I reworded some of the sentences that used e.g. to either make for example flow better, or removed it all together. Let me know what you think!

[Fishrock123]

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]

I added some examples, PTAL. I also rebased against master to fix merge conflicts.

[varjmes]

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.

[ashleygwilliams]

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?

[ashleygwilliams]

i'd like to get this merge asap, so if this is put into a different file(doc/POLICY_ISSUES.md) or something and then linked in the top level CONTRIBUTING.md i can work on a doc/PROGRAM_ISSUES. and we'd be good to go, thoughts?

[ashleygwilliams]

oh also. i would really like a line, in bold, at the top of contributing that says "PEOPLE OVER PEDANTRY" which means if you are overwhelmed by these rules just contribute and we'll help you find the right way.

[varjmes]

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

agree, a long document is less likely to be read (unless you are me who has spent 6 hours in total so far reading this inclusivity stuff :P)

[varjmes]

Oh! I just recalled a great thing you can do help issue creation that we can add to this.

Over in the Hoodie Editorial team, if someone wants to pitch a blog post they can click this link and it will automatically create an issue with a markdown file of suggested questions to answer.

To create the title= and body= portions of the URL, paste the title text and body text (separately) here: http://meyerweb.com/eric/tools/dencoder/, press encode to get the URL encoded text and form the URL.

Might we do this for each of the pitch templates, meaning the issue can be auto created with the pertinent subheadings?

[ashleygwilliams]

WHOA that is brilliant, @Charlotteis. yes yes yes

[ghost]

@Charlotteis that sounds amazing, i did not even know that existed.

[varjmes]

@Charlotteis that sounds amazing, i did not even know that existed.

all thanks to my lovely Hoodie-colleague [at]gr2m that I knew myself :)

[beaugunderson]

ok, done with my review! :sparkles:

[nebrius]

Thanks everyone for the reviews, I know this one is a little denser than most :) I think I addressed everyone's concerns, PTAL!

[varjmes]

Here is a magic URL I made to show how we could help people make 'Question' issues click

[beaugunderson]

@Charlotteis those URLs are totally going to come in handy, thank you :)

[ashleygwilliams]

@nebrius this still needs to be moved out of CONTRIBUTING.md and into docs/issues.md or something like that

[nebrius]

@nebrius this still needs to be moved out of CONTRIBUTING.md and into docs/issues.md or something like that

D'oh! Last run through I only read the inline comments, sorry! 😅

Here is a magic URL I made to show how we could help people make 'Question' issues click

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?

[nebrius]

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?

[nebrius]

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?

[ghost]

if we do get one of these magic URLs (which i'm absolutely for), then let's also put it somewhere in CONTRIBUTING.md. there's this little thing when creating a new issue from blank:

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

[beaugunderson]

@nebrius just responded to the one thing that i hadn't responded to that was still an open question, i think :)

[varjmes]

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?

Probably better to have 'fill purpose here' unless we want people to delete several paragraphs about hot dogs every time they open an issue :)

[ashleygwilliams]

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?

[nebrius]

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.

[ghost]

fine by me, i'll open a separate PR when it's time

[ghost]

LGTM! :sunglasses:

[ashleygwilliams]

wooo, merging. awesome job for spearheading this @nebrius -- and thanks to everyone for participating so thoughtfully!