247 establish proposals format and process

proposals/000-template.md

@@ -0,0 +1,95 @@
+# [Title]
+
+[N.B: Replace text in square brackets with your text]
+
+| author             | date-accepted                         | pr-url                                          | implemented                                              |
+| ------------------ | ------------------------------------- | ----------------------------------------------- | -------------------------------------------------------- |
+| [Full author name] | [Date when the proposal was accepted] | [URL of a PR where this proposal was discussed] | [normalizer version where this proposal was implemented] |
+
+## Motivation
+
+[
+Give a strong reason for why you need this change.
+Describe the use case as clearly as possible and give an example.
+Explain how the status quo is insufficient or not ideal.
+
+A good Motivation section is often driven by examples and real-world scenarios.
+]
+
+## Proposed Change Specification
+
+[
+Specify the change in precise, comprehensive yet concise language.
+Avoid words like "should" or "could".
+Strive for a complete definition.
+Your specification may include,
+
+- LBNF grammar and semantics of any new syntactic constructs (see [LBNF reference](https://bnfc.readthedocs.io/en/latest/lbnf.html)).
+- how the proposed change interacts with existing normalizer features, in case that is otherwise ambiguous
+
+Strive for *precision*.
+
+Think about corner cases. Write down
+general rules and invariants.
+
+Note, however, that this section should focus on a precise
+*specification*; it need not (and should not) devote space to
+*implementation* details -- the "Implementation Plan" section can be used for that.
+
+The specification can, and almost always should, be illustrated with
+*examples* that illustrate corner cases. But it is not sufficient to
+give a couple of examples and regard that as the specification! The
+examples should illustrate and elucidate a clearly-articulated
+specification that covers the general case.
+]
+
+## Examples
+
+[
+This section illustrates the specification through the use of examples of the
+language change proposed. It is best to exemplify each point made in the
+specification, though perhaps one example can cover several points. Contrived
+examples are OK here. If the Motivation section describes something that is
+hard to do without this proposal, this is a good place to show how easy that
+thing is to do with the proposal.
+]
+
+## Effect and Interactions
+
+[
+Your proposed change addresses the issues raised in the
+motivation. Explain how.
+
+Also, discuss possibly contentious interactions with existing language or normalizer
+features. Complete this section with potential interactions raised
+during the PR discussion.
+]
+
+## Alternatives
+
+[
+List alternative designs to your proposed change. Both existing
+workarounds, or alternative choices for the changes. Explain
+the reasons for choosing the proposed change over these alternative:
+*e.g.* they can be cheaper but insufficient, or better but too
+expensive. Or something else.
+
+The PR discussion often raises other potential designs, and they should be
+added to this section. Similarly, if the proposed change
+specification changes significantly, the old one should be listed in
+this section.
+]
+
+## Unresolved Questions
+
+[
+Explicitly list any remaining issues that remain in the conceptual design and
+specification. Please do not list *implementation* issues.
+]
+
+## Implementation Plan
+
+[
+(Optional) If accepted who will implement the change?
+Which other resources and prerequisites are required for implementation?
+]

proposals/README.md

@@ -0,0 +1,19 @@
+# Proposal
+
+A Proposal is a document describing a proposed change to the normalizer.
+
+## Proposal format
+
+- Template for proposals should resemble the [ghc-proposals template](https://github.com/ghc-proposals/ghc-proposals/blob/master/proposals/0000-template.md).
+- Proposal file names should consist of an index, a title, and the `.md` extension
+  - Example: `001-pattern-matching-on-paths.md`.
+- PR names should follow the format `[proposal] proposal_title`
+  - Example: `[proposal] Pattern matching on paths`.
+
+## Proposal process
+
+- (No label.) The author drafts a proposal.
+- (No label.) The author submits the proposal for discussion, as a pull request against this repository.
+- Label: [proposal under review](https://github.com/objectionary/normalizer/labels/proposal%20under%20review). The normalizer team discusses the proposal in the commit section of the pull request, while the author refines the proposal. This phase lasts as long as necessary.
+- Eventually, the normalizer team rejects a proposal (label: [proposal rejected](https://github.com/objectionary/normalizer/labels/proposal%20rejected)), or passes it back to the author for review (label: [proposal needs revision](https://github.com/objectionary/normalizer/labels/Proposal%20needs%20revision)), or accepts it (label: [proposal  accepted](https://github.com/objectionary/normalizer/labels/proposal%20accepted)).
+- Label: [proposal implemented](https://github.com/objectionary/normalizer/labels/proposal%20implemented). Once a proposal is accepted, it still has to be implemented. The author may do that, or someone else. We mark the proposal as “implemented” once it hits normalizer master branch (and we are happy to be nudged to do so by email, GitHub issue, or a comment on the relevant pull request) and the corresponding documentation on the site is updated.