Add central policies document #434
Conversation
POLICIES.md
Outdated
|
|
||
| <#simple-onboarding> | ||
|
|
||
| ## Event Checklist |
There was a problem hiding this comment.
I wonder if the event triggers should be at the top of the file? Thinking in terms of how it will be used, that would be a great reference/index into the list of policies
POLICIES.md
Outdated
|
|
||
| ## Policy Descriptions | ||
|
|
||
| ### Multiple file submissions [[1](https://github.com/exercism/xjava/issues/365#issuecomment-292533120)] |
There was a problem hiding this comment.
What are the bracketed numbers meant to indicate? Are these intended to be the issue number and just aren't yet updated?
There was a problem hiding this comment.
Just references that are relevant to the policy. There could in theory be more than one, in which case I would expect to see this written as [1, 2].
POLICIES.md
Outdated
| 2. your proposed changes; and | ||
| 3. how your proposal balances your own perspective with those already raised during prior discussions. | ||
|
|
||
| ## Policy Descriptions |
There was a problem hiding this comment.
Does it make sense to sort the policies in the order they are mentioned in the table? Might help make it more navigable.
|
@jtigger updated! Ideally I'd like to be able to link occurrences of the policies in the event table to their long descriptions, but I haven't figure out the right way to do that without lots of duplication :/ |
|
This is a little unorthodox, but what if we edit the individual policy issues, themselves, and stick the summary there, throw down a markdown and keep the original text? Then, this policy page is "merely" an introduction to the concept, the event-to-policy mapping but nothing else...? Perhaps a little less "destructive" approach would be to create brand new issues, mark those as policy that reference back to the original issue sparking the discussion...? |
|
Hmm... I like that this document can currently be treated as standalone once a policy has been settled upon (for now). I'd hate for people to have to jump all around the xjava repo from this document to learn about what the policies are. OTOH I have no problem with jumping around if one wants to understand the why behind a policy. I guess that's a long way of saying; I like the current structure better, I think? Also interested in what other @exercism/java maintainers think, since it's mostly a resource for that group! I can easily be convinced either way by tie-breaking input :) |
|
... yeah, on second thought, these ideas don't mutate very often... seems like the duplication could be manageable? |
|
Agreed; let me throw that in and see how it feels :) |
|
Oh, ew @ bracketed number inclusion... I'll see about moving that so that it's not part of the anchor. |
|
I think this is great, @stkent. Are you good with this, as is? If so, merge away! |
|
I think so - and like everything else, if it doesn't sit right post-merge, we can iterate freely. Merging! |
Closes #425.
I surveyed our policy label to seed this document, and also included a new PR template that links to the policy checklist (for ease of PR review).
Some of the relative links might not be quite right; it's hard to test that off-GitHub.
Feedback welcome!