Label for policy decisions "hidden" in issues?

[Insti]

Would it be useful to add a policy label to issues that contain the discussions/decrees that lead to various decisions that shape Exercism, so that when the issues are closed and PRs are merged it's still possibly to easily find them again?

Ideally all these policy decisions would be documented in some kind of reference document, but that is not currently the case, and this would be a good step toward making them more discoverable.

For example the current discussion of use of ASCII/non-ASCII characters in tests will eventually be resolved and closed.
It would be good to be able to tag this with a label that could be searched for next time the issue comes up.

This would also apply to many other issues such as gamification related suggestions, why we have a permissive Rubocop configuration, what the intention of particularly exercises are, and so on.

Thoughts?

[petertseng]

Doing this seems like a positive change. I think I would not hesitate to apply the labels soon. Or at least collect a list of issues that have interesting decisions, since that process is separate from what to do with them.

Another idea that is similar is exercism/problem-specifications#382 - it seems that idea is more about per-exercise decisions, whereas there may be more global decisions that should be collected elsewhere. These ideas are not mutually exclusive.

[jtigger]

This is a great idea, @Insti!

As Exercism continues to mature, the ecosystem needs to have organizational memory to avoid the churn associated with rehashing the same question over and over (gamification, anyone?). That said, one caution: GitHub issues labeled as "policy" represent a rough consensus at a point in time and should be considered mutable as the group's context shifts.

[Insti]

GitHub issues labeled as "policy" represent a rough consensus at a point in time and should be considered mutable as the group's context shifts.

Certainly. 'Policy' issues should always be up for discussion and tags can be removed if opinion changes.

[kytrinyx]

Would it be useful to add a policy label to issues that contain the discussions/decrees that lead to various decisions that shape Exercism, so that when the issues are closed and PRs are merged it's still possibly to easily find them again?

@Insti I absolutely love this idea. Let's make it so!

[jtigger]

I've created the "Policy" label (deep purple background) in:

• exercism.io
• discussions
• x-common

[jtigger]

Next step: as such discussions stabilize, it makes sense to summarize and somewhat codify such decisions (the big one ATM is "safeguarding intrinsic motivation" aka "just say no to gamification").

So, imagine a Markdown document somewhere that summarizes these apparent decisions and links into the "policy"'ed issues for details.

• where would this document live?
  • it should be prominent to the primary audience: users who have great ideas that might be influenced by such "policy"s.
• what are the triggering events that signal that such a "policy" should be included there?

[kytrinyx]

How about having a policy doc here in the docs/ directory of the exercism/exercism.io repo?

We might decide that we want a whole directory with one document per policy and a README for the table of contents, but until there's an explicit need for it, maybe we can just keep it like this.

We might also end up with so much documentation that we want to stick it in a separate repo. Now that we can pin repos, that wouldn't be such a terrible thing. But again: we have this docs/ directory, it seems like we could just use that.

Then we can reference it from the Contributing Guide.

I think if a discussion is lively and has an interesting outcome that doesn't necessarily get encoded into the codebase anywhere, it should get documented in the policy document. For now let's just start documenting things and see what happens. We might get a clearer idea of when things should go in there.

[kytrinyx]

For the moment, we've not been documenting policies, but we have been labeling them, which has been really great.

We can get a list of all issues labeled "policy" for the entire organization here: https://github.com/search?q=org%3Aexercism+label%3Apolicy

I don't think we need to document all the policies directly in a file named policies.md or similar.

I think that these decisions should be a part of existing documentation (in the broader context) where relevant. We might not always have that documentation, in which case it needs to be added.

For these issues, I think that when the discussion has concluded, we should:

1. Summarize the important points and questions in the discussion.
2. Figure out what the broader context is.
3. Figure out if we have documentation about that.
4. Open an issue that links to the policy to

• update the existing documentation to include the policy (if it exists)
• add the missing documentation about the broader topic (if it doesn't)

Then close the policy discussion.

[kytrinyx]

Closing, as we more or less have been doing this for the past year. Let's keep doing so :)