Bootstrap RFCs and add initial RFC (#188)

* Add template and rfc rfc

* Remove issue template

* Add generate script for SUMMARY.md

* Generage SUMMARY.md file

* generate summary

* Update rfc process

* Add symlink to rfc

* Add notes to README

.github/ISSUE_TEMPLATE/RFC.md

@@ -1,20 +0,0 @@
----
-name: "\U0001F4AC Request For Comment (RFC)"
-about: Feature discussion
-title: ''
-labels: rfc
-assignees: ''
-
----
-
-<!--- Provide a detailed summary of the issue here -->
-
-## 🔦 Context
-
-<!--- How has this issue affected you? What are you trying to accomplish? -->
-
-<!--- Providing context helps us come up with a solution that is most useful in the real world -->
-
-## 💻 Examples
-
-<!-- Examples help us understand the requested feature better -->

.github/workflows/build-deploy-docs.yml

@@ -26,7 +26,9 @@ jobs:
       - name: Build
         working-directory: docs
         shell: bash
-        run: mdbook build
+        run: |
+          ./generate-summary.sh
+          mdbook build
       - name: API Documentation
         shell: bash
         run: cargo doc -p maplibre --no-deps --lib --document-private-items

README.md

@@ -132,7 +132,7 @@ Install [rustup](https://rustup.rs/) because this is the recommended way of sett
 The toolchain will be automatically downloaded when building this project.
 See [./rust-toolchain.toml](./rust-toolchain.toml) for more details about the toolchain.
 
-## Documentation
+## API Documentation
 
 This generates the documentation for this crate and opens the browser. This also includes the documentation of every
 dependency.
@@ -143,6 +143,16 @@ cargo doc --open
 
 You can also view the up-to-date documentation [here](https://maplibre.org/maplibre-rs/docs/api/maplibre/).
 
+## Book
+
+The maplibre-rs book features a high-level overview over the project from a user and development perspective.
+
+## RFCs
+
+We established an RFC process which must be used to describe major changes to maplibre-rs.
+Current RFCs can be browsed in the [book](https://maplibre.org/maplibre-rs/book/rfc/0001-rfc-process.html).
+
+
 ## Citing
 
 If you wish to cite this project in a scientific publication use the following format:

docs/.gitignore

@@ -1,2 +1,5 @@
 book
-*.bkp
+*.bkp
+
+src/SUMMARY-rfc.md
+src/SUMMARY.md

docs/generate-summary.sh

@@ -0,0 +1,14 @@
+#!/usr/bin/env bash
+
+set -e
+
+printf -- '- [RFCs](rfc/0001-rfc-process.md)\n\n' > src/SUMMARY-rfc.md
+
+find ./src/rfc ! -type d -name '*.md' -print0 \
+  | sort -z \
+  | while read -r -d '' file;
+do
+    printf -- '  - [%s](rfc/%s)\n' "$(basename "$file" ".md")" "$(basename "$file")"
+done >> src/SUMMARY-rfc.md
+
+cat src/SUMMARY-book.md src/SUMMARY-rfc.md > src/SUMMARY.md

docs/src/SUMMARY-book.md

@@ -13,7 +13,6 @@
   - [Building Libraries](./development-guide/building-libraries.md)
   - [Debugging](./development-guide/debugging.md)
 
-
 - [Development Documents](./development-documents/index.md)
   - [Architecture](./development-documents/architecture.md)
   - [Design](./development-documents/design.md)
@@ -27,5 +26,3 @@
 
 - [Appendix](./appendix/index.md)
   - [Link Collection](./appendix/link-collection.md)
-
-

docs/src/rfc/0000-template.md

@@ -0,0 +1,112 @@
+- Feature Name: (fill me in with a unique ident, `my_awesome_feature`)
+- Start Date: (fill me in with today's date, YYYY-MM-DD)
+- RFC PR: [maplibre/maplibre-rs#0000](https://github.com/maplibre/maplibre-rs/pull/0000)
+- maplibre-rs Issue: [maplibre/maplibre-rs#0000](https://github.com/maplibre/maplibre-rs/issues/0000)
+
+# Summary
+
+[summary]: #summary
+
+One paragraph explanation of the feature.
+
+# Motivation
+
+[motivation]: #motivation
+
+Why are we doing this? What use cases does it support? What is the expected outcome?
+
+# Guide-level explanation
+
+[guide-level-explanation]: #guide-level-explanation
+
+Explain the proposal as if it was already included in the project and you were teaching it to another maplibre-rs user.
+That generally means:
+
+- Introducing new named concepts.
+- Explaining the feature largely in terms of examples.
+- Explaining how maplibre-rs users should *think* about the feature, and how it should impact the way they use
+  maplibre-rs. It should explain the impact as concretely as possible.
+- If applicable, provide sample error messages, deprecation warnings, or migration guidance.
+- If applicable, describe the differences between teaching this to existing maplibre-rs users and new maplibre-rs users.
+
+For implementation-oriented RFCs (e.g. for internals), this section should focus on how maplibre-rs contributors should
+think about the change, and give examples of its concrete impact. For policy RFCs, this section should provide an
+example-driven introduction to the policy, and explain its impact in concrete terms.
+
+# Reference-level explanation
+
+[reference-level-explanation]: #reference-level-explanation
+
+This is the technical portion of the RFC. Explain the design in sufficient detail that:
+
+- Its interaction with other features is clear.
+- It is reasonably clear how the feature would be implemented.
+- Corner cases are dissected by example.
+
+The section should return to the examples given in the previous section, and explain more fully how the detailed
+proposal makes those examples work.
+
+# Drawbacks
+
+[drawbacks]: #drawbacks
+
+Why should we *not* do this?
+
+# Rationale and alternatives
+
+[rationale-and-alternatives]: #rationale-and-alternatives
+
+- Why is this design the best in the space of possible designs?
+- What other designs have been considered and what is the rationale for not choosing them?
+- What is the impact of not doing this?
+
+# Prior art
+
+[prior-art]: #prior-art
+
+Discuss prior art, both the good and the bad, in relation to this proposal.
+A few examples of what this can include are:
+
+- Does this feature exist in other map renderers and what experience have their community had?
+- For community proposals: Is this done by some other community and what were their experiences with it?
+- For other teams: What lessons can we learn from what other communities have done here?
+- Papers: Are there any published papers or great posts that discuss this? If you have some relevant papers to refer to,
+  this can serve as a more detailed theoretical background.
+
+This section is intended to encourage you as an author to think about the lessons from other renderers, provide readers
+of your RFC with a fuller picture.
+If there is no prior art, that is fine - your ideas are interesting to us whether they are brand new or if it is an
+adaptation from other map renderers.
+
+Note that while precedent set by other map renderers is some motivation, it does not on its own motivate an RFC.
+
+# Unresolved questions
+
+[unresolved-questions]: #unresolved-questions
+
+- What parts of the design do you expect to resolve through the RFC process before this gets merged?
+- What parts of the design do you expect to resolve through the implementation of this feature before stabilization?
+- What related issues do you consider out of scope for this RFC that could be addressed in the future independently of
+  the solution that comes out of this RFC?
+
+# Future possibilities
+
+[future-possibilities]: #future-possibilities
+
+Think about what the natural extension and evolution of your proposal would
+be and how it would affect the renderer and project as a whole in a holistic
+way. Try to use this section as a tool to more fully consider all possible
+interactions with the project and renderer in your proposal.
+Also consider how this all fits into the roadmap for the project
+and of the relevant sub-team.
+
+This is also a good place to "dump ideas", if they are out of scope for the
+RFC you are writing but otherwise related.
+
+If you have tried and cannot think of any future possibilities,
+you may simply state that you cannot think of anything.
+
+Note that having something written down in the future-possibilities section
+is not a reason to accept the current or a future RFC; such notes should be
+in the section on motivation or rationale in this or subsequent RFCs.
+The section merely provides additional information.

docs/src/rfc/0001-rfc-process.md

@@ -0,0 +1,120 @@
+- Start Date: 2022-10-29
+- RFC PR: [maplibre/maplibre-rs#??](https://github.com/maplibre/maplibre-rs/pull/??)
+- maplibre-rs Issue: N/A
+
+# Summary
+
+The "RFC" (request for comments) process is intended to provide a
+consistent and controlled path for new features to enter the map renderer
+and standard libraries, so that all stakeholders can be confident about
+the direction the map renderer is evolving in.
+
+This RFC is copied from [rust-lang/rfcs](https://github.com/rust-lang/rfcs).
+Thanks to everyone who contributed to the Rust RFC process RFC! Thanks for the
+great inspiration!
+
+# Motivation
+
+The freewheeling way that we add new features to maplibre-rs has been good for
+early development, but for maplibre-rs to become a mature platform we need to
+develop some more self-discipline when it comes to changing the system.
+This is a proposal for a more principled RFC process to make it
+a more integral part of the overall development process, and one that is
+followed consistently to introduce features to maplibre-rs.
+
+# Detailed design
+
+Many changes, including bug fixes and documentation improvements can be
+implemented and reviewed via the normal GitHub pull request workflow.
+
+Some changes though are "substantial", and we ask that these be put
+through a bit of a design process and produce a consensus among the maplibre-rs
+community.
+
+## When you need to follow this process
+
+You need to follow this process if you intend to make "substantial"
+changes to the maplibre-rs distribution. What constitutes a "substantial"
+change is evolving based on community norms, but may include the following.
+
+- Any semantic or syntactic change to the map renderer that is not a bugfix.
+- Removing map renderer features, including those that are feature-gated.
+
+Some changes do not require an RFC:
+
+- Rephrasing, reorganizing, refactoring, or otherwise "changing shape
+  does not change meaning".
+- Additions that strictly improve objective, numerical quality
+  criteria (warning removal, speedup, better platform coverage, more
+  parallelism, trap more errors, etc.)
+- Additions only likely to be _noticed by_ other developers-of-maplibre-rs,
+  invisible to users-of-maplibre-rs.
+
+If you submit a pull request to implement a new feature without going
+through the RFC process, it may be closed with a polite request to
+submit an RFC first.
+
+## What the process is
+
+In short, to get a major feature added to maplibre-rs, one must first get the
+RFC merged into the RFC repo as a markdown file. At that point the RFC
+is 'active' and may be implemented with the goal of eventual inclusion
+into maplibre-rs.
+
+* Fork the repo https://github.com/maplibre/maplibre-rs
+* Copy `rfc/0000-template.md` to `rfc/0000-my-feature.md` (where
+  'my-feature' is descriptive. don't assign an RFC number yet).
+* Fill in the RFC
+* Submit a pull request. The pull request is the time to get review of
+  the design from the larger community.
+* Build consensus and integrate feedback. RFCs that have broad support
+  are much more likely to make progress than those that don't receive any
+  comments.
+
+Eventually, somebody on the maplibre-rs team will either accept the RFC by
+merging the pull request, at which point the RFC is 'active', or
+reject it by closing the pull request.
+
+Who ever merges the RFC should do the following:
+
+* Assign an id, using the PR number of the RFC pull request. (If the RFC
+  has multiple pull requests associated with it, choose one PR number,
+  preferably the minimal one.)
+* Add the file in the `docs/src/rfc/` directory.
+* Create a corresponding issue on [maplibre-rs repo](https://github.com/maplibre/maplibre-rs)
+* Fill in the remaining metadata in the RFC header, including links for
+  the original pull request(s) and the newly created maplibre-rs issue.
+* Communicate that given RFC is now considered 'active' on the chat platform of maplibre-rs.
+* Commit everything.
+
+Once an RFC becomes active then authors may implement it and submit the
+feature as a pull request to the maplibre-rs repo. An 'active' is not a rubber
+stamp, and in particular still does not mean the feature will ultimately
+be merged; it does mean that in principle all the major stakeholders
+have agreed to the feature and are amenable to merging it.
+
+Modifications to active RFC's can be done in followup PR's. An RFC that
+makes it through the entire process to implementation is considered
+'complete'; an RFC that fails after becoming active is 'inactive'.
+
+# Alternatives
+
+Retain the current informal RFC process. The newly proposed RFC process is
+designed to improve over the informal process in the following ways:
+
+* Discourage unactionable or vague RFCs
+* Ensure that all serious RFCs are considered equally
+* Give confidence to those with a stake in maplibre-rs's development that they
+  understand why new features are being merged
+
+As an alternative, we could adopt an even stricter RFC process than the one proposed here. 
+If desired, we should likely look to Python's [PEP] process for inspiration.
+
+# Unresolved questions
+
+1. Does this RFC strike a favorable balance between formality and agility?
+2. Does this RFC successfully address the aforementioned issues with the current
+   informal RFC process?
+3. Should we retain rejected RFCs in the archive?
+
+[PEP]: http://legacy.python.org/dev/peps/pep-0001/

rfc

@@ -0,0 +1 @@
+docs/src/rfc