[Proposal] Add a lightweight proposal process (#49)

[Proposal] Add a lightweight proposal process

### Motivation

To ensure that we include all the important considerations for every non-trivial API change, and solicit feedback in a consistent way, let's introduce a lightweight proposal process based on Swift evolution.

### Modifications

Added a template and a Proposals page that lists them all, plus linked to it from the relevant doc pages.

### Result

Contributors will be able to just duplicate the template and fill in their proposal.

### Test Plan

Previewed docs locally and verified the navigation works.


Reviewed by: simonjbeaumont

Builds:
     ✔︎ pull request validation (5.8) - Build finished. 
     ✔︎ pull request validation (5.9) - Build finished. 
     ✔︎ pull request validation (nightly) - Build finished. 
     ✔︎ pull request validation (soundness) - Build finished. 

#49

Author: czechboy0

Sources/swift-openapi-generator/Documentation.docc/Articles/Contributing-to-Swift-OpenAPI-Generator.md

@@ -24,6 +24,8 @@ The generated Swift code depends on the runtime library, so some features might
 
 Similarly, any changes to the transport and middleware protocols in the runtime library must consider the impact on existing existing transport and middleware implementation packages.
 
+> Tip: For non-trivial changes affecting the API, consider writing a proposal. For more, check out <doc:Proposals>.
+
 ### Testing the generator
 
 The generator relies on a mix of unit and integration tests.

Sources/swift-openapi-generator/Documentation.docc/Proposals/Proposals.md

@@ -0,0 +1,44 @@
+# Proposals
+
+Collaborate on API changes to Swift OpenAPI Generator by writing a proposal.
+
+## Overview
+
+For non-trivial changes that affect the public API, the Swift OpenAPI Generator project adopts a ligthweight version of the [Swift Evolution](https://github.com/apple/swift-evolution/blob/main/process.md) process.
+
+Writing a proposal first helps discuss multiple possible solutions early, apply useful feedback from other contributors, and avoid reimplementing the same feature multiple times.
+
+While it's encouraged to get feedback by opening a pull request with a proposal early in the process, it's also important to consider the complexity of the implementation when evaluating different solutions (as per <doc:Project-scope-and-goals>). For example, this might mean including a prototype implementation of the feature in the same PR as the proposal document.
+
+> Note: The goal of this process is to help solicit feedback from the whole community around the project, and we will continue to refine the proposal process itself. Use your best judgement, and don't hesitate to propose changes to the proposal structure itself!
+
+### Steps
+
+1. Make sure there's a GitHub issue for the feature or change you would like to propose.
+2. Duplicate the `SOAR-NNNN.md` document and replace `NNNN` with the next available proposal number.
+3. Link the GitHub issue from your proposal, and fill in the proposal.
+4. Open a pull request with your proposal and solicit feedback from other contributors.
+5. Once a maintainer confirms that the proposal is ready for review, the state is updated accordingly. The review period is 7 days, and ends when one of the maintainers marks the proposal as Ready for Implementation, or Deferred.
+6. Before the pull request is merged, there should be an implementation ready, either in the same pull request, or a separate one, linked from the proposal.
+7. The proposal is considered Approved once the implementation and proposal PRs have been merged.
+
+If you have any questions, tag [Honza Dvorsky](https://github.com/czechboy0) or [Si Beaumont](https://github.com/simonjbeaumont) in your issue or pull request on GitHub.
+
+### Possible review states
+
+- Awaiting Review
+- In Review
+- Ready for Implementation
+- Approved
+- Deferred
+
+### Possible affected components
+
+- generator
+- runtime
+- client transports
+- server transports
+
+## Topics
+
+- <doc:SOAR-NNNN>

Sources/swift-openapi-generator/Documentation.docc/Proposals/SOAR-NNNN.md

@@ -0,0 +1,57 @@
+# SOAR-NNNN
+
+Feature name (template proposal)
+
+## Overview
+
+- Proposal: SOAR-NNNN
+- Author(s): [Author 1](https://github.com/swiftdev), [Author 2](https://github.com/swiftdev)
+- Status: **Awaiting Review**
+- Issue: [apple/swift-openapi-generator#1](https://github.com/apple/swift-openapi-generator/issues/1)
+- Implementation:
+    - [apple/swift-openapi-generator#1](https://github.com/apple/swift-openapi-generator/pull/1)
+- Affected components:
+    - generator
+    - runtime
+    - client transports
+    - server transports
+- Related links:
+    - [Swift Evolution](https://www.swift.org/swift-evolution/)
+
+### Introduction
+
+A short, one-sentence overview of the feature or change.
+
+### Motivation
+
+Describe the problems that this proposal aims to address, and what workarounds adopters have to employ currently, if any.
+
+### Proposed solution
+
+Describe your solution to the problem. Provide examples and describe how they work. Show how your solution is better than current workarounds.
+
+This section should focus on what will change for the _adopters_ of Swift OpenAPI Generator.
+
+### Detailed design
+
+Describe the implementation of the feature, a link to a prototype implementation is encouraged here.
+
+This section should focus on what will change for the _contributors_ to Swift OpenAPI Generator.
+
+### API stability
+
+Discuss the API implications, making sure to considering all of:
+- runtime public API
+- runtime "Generated" SPI
+- existing transport and middleware implementations
+- generator implementation affected by runtime API changes
+- generator API (config file, CLI, plugin)
+- existing and new generated adopter code
+
+### Future directions
+
+Discuss any potential future improvements to the feature.
+
+### Alternatives considered
+
+Discuss the alternative solutions considered, even during the review process itself.

Sources/swift-openapi-generator/Documentation.docc/Swift-OpenAPI-Generator.md

@@ -75,6 +75,7 @@ The generated code, runtime library, and transports are supported on more platfo
 ### Getting involved
 - <doc:Project-scope-and-goals>
 - <doc:Contributing-to-Swift-OpenAPI-Generator>
+- <doc:Proposals>
 
 [openapi]: https://openapis.org
 [tools]: https://openapi.tools