Add design proposal guidelines (#417)
This commit is contained in:
@@ -15,3 +15,18 @@ If you want to contribute code:
|
|||||||
1. Prefix your commit messages with the platform(s) your changes affect: `[ios]` or `[macos]`.
|
1. Prefix your commit messages with the platform(s) your changes affect: `[ios]` or `[macos]`.
|
||||||
|
|
||||||
Please note the special instructions for contributing new source code files, asset files, or user-facing strings to the [iOS SDK](platform/ios/DEVELOPING.md) or [macOS SDK](platform/macos/DEVELOPING.md).
|
Please note the special instructions for contributing new source code files, asset files, or user-facing strings to the [iOS SDK](platform/ios/DEVELOPING.md) or [macOS SDK](platform/macos/DEVELOPING.md).
|
||||||
|
|
||||||
|
## Design Proposals
|
||||||
|
|
||||||
|
If you would like to change MapLibre GL Native in a substantial way, we recommend that you write a Design Proposal. Examples for substantial changes could be if you would like to split the mono-repo or if you would like to introduce shaders written in Metal.
|
||||||
|
|
||||||
|
The purpose of a Design Proposal is to collectively think through a problem before starting to implement a solution. Every implementation has advantages and disadvantages. We can discuss them in a Design Proposal, and once we reach an agreement, we follow the guidelines in the Design Proposal and work on the implementation.
|
||||||
|
|
||||||
|
The steps for a Design Proposal are the following:
|
||||||
|
|
||||||
|
1. Copy the Design Proposal template in the `design-proposals/` folder.
|
||||||
|
2. Use a filename with the current date and a keyword, e.g., `design-proposals/2022-09-15-metal.md`.
|
||||||
|
3. Fill out the template and submit a pull request.
|
||||||
|
4. Discuss the details of your Design Proposal with the community in the pull request. Adjust where needed.
|
||||||
|
5. Call a vote on the Design Proposal once discussions have settled. People in favor of your Design Proposal shall approve the pull request. People against your Design Proposal shall comment on the pull request with something like "Rejected".
|
||||||
|
6. Give the community at least 72 hours to vote. If a majority of the people who voted accept your Proposal, it can be merged.
|
||||||
|
|||||||
21
design-proposals/2022-09-02-design-proposal-template.md
Normal file
21
design-proposals/2022-09-02-design-proposal-template.md
Normal file
@@ -0,0 +1,21 @@
|
|||||||
|
# Design Proposal Template
|
||||||
|
|
||||||
|
## Motivation
|
||||||
|
|
||||||
|
Describe the problem you would like to solve.
|
||||||
|
|
||||||
|
## Proposed Change
|
||||||
|
|
||||||
|
Describe what you would like to do to solve the problem. This part is the actual design proposal and can be extensive with multiple subsections.
|
||||||
|
|
||||||
|
## API Modifications
|
||||||
|
|
||||||
|
Outline what modifications you expect on the public API due to your change.
|
||||||
|
|
||||||
|
## Migration Plan and Compatibility
|
||||||
|
|
||||||
|
If your change is incompatible with existing APIs, draft a migration plan to help users adapting to the new version once your change is completed.
|
||||||
|
|
||||||
|
## Rejected Alternatives
|
||||||
|
|
||||||
|
Discuss what alternatives to your proposed change you considered and why you rejected them.
|
||||||
Reference in New Issue
Block a user