Create proposals directory

[fpiwowarczyk]

Problem to solve

Often, designing software developers are creating documents called ADRs (Architectural Decision Record) which let's you to see decision making proces for given change. We have similar documents in issues section, but it is hard to follow after they are closed and they miss sometimes important details like order of decisions/ what tradeoffs we accepted etc.

Currently we are thinking about doing v2 of spec, I think it is good time to record why spec has changed in some direction.

Proposal

Let's create ADR/Proposals directory in spec repository and store there most important, accepted decisions about spec to let anyone new read them and see why we choose given option.

Further details

I think this should have ordered structure and should record most important decisions. I think even having document that links issue it resolves would be enough to show person from outside order of our decisions.

Examples of decisions could be placed there:

• Removing displayName from spec
• Changing apiVersion to openslo.com
• Put labels into all spec objects.
• etc.

Proposals--|
           |--- 00-createAcceptedProposalsRecord.md
           |--- 01-removeDisplayNameFromMetadata.md
           |--- 02-changeApiVersion.md 

[nieomylnieja]

I think that's a great idea, I've been thinking about this too recently, let's do it :)

[proffalken]

Not 100% against this, but would https://docs.github.com/en/discussions be something to consider as well?

Issues/Discussions are better (IMO anyway!) at showing the way that a decision was reached, whereas ADR's are good for showing the decision that was taken and a summary of the process taken to reach it.

Perhaps once a decision has been taken it can be transferred from the issue/discussion to the proposals folder?

I guess my main concern is "How do folks within the community show their support/dissent within a Markdown document?" - on an issue/discussion then a simple 👍 or 👎 is perfect, but having to fork, edit, and commit when all I want to do is signal support feels like a lot of overhead?

[fpiwowarczyk]

I haven't used discussions so i cannot say if they are good fit, but we can take closer look and try it. One downside of this I see is that not only for me it isn't well known feature/first place to look at when looking for decisions about spec.

Exactly that was my thinking we are not stopping using issues, they should work like they are currently working, but when decision is taken just add new document into proposal folder, you can also link issue there. We won't have to show support for markdown document because we should place there only things that are implemented already just to should decision process for new folks that may have some concerns about current look of spec/ remind us why we reach given decision.

[proffalken]

Ah, cool, we're talking about the same approach then, that's fine, objection removed! 😂

[programmer04]

I've just enabled discussions

• Welcome to OpenSLO Discussions! #251

🎉