Skip to content

Commit c3f265f

Browse files
authored
Add proposal process documentation (cadence-workflow#2127)
1 parent cb7e56f commit c3f265f

9 files changed

+293
-2
lines changed

PROPOSALS.md

+42
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,42 @@
1+
# Proposing Changes to Cadence
2+
3+
## Introduction
4+
5+
The design process for changes to Cadence is modeled on the [proposal process used by the M3 project](https://github.com/m3db/proposal).
6+
7+
## Process
8+
9+
- [Create an issue](https://github.com/uber/cadence/issues/new) describing the proposal.
10+
11+
- Like any GitHub issue, a proposal issue is followed by an initial discussion about the suggestion. For Proposal issues:
12+
13+
- The goal of the initial discussion is to reach agreement on the next step: (1) accept, (2) decline, or (3) ask for a design doc.
14+
- The discussion is expected to be resolved in a timely manner.
15+
- If the author wants to write a design doc, then they can write one.
16+
- A lack of agreement means the author should write a design doc.
17+
18+
- If a Proposal issue leads to a design doc:
19+
20+
- The design doc should be presented as a Google Doc and must follow [the template](https://docs.google.com/document/d/1hpWpy5MB5l8uXfnl23lebhx-dvo79vb1jFUOyAtIHJw/edit?usp=sharing).
21+
- The design doc should be linked from the opened GitHub issue.
22+
- The design doc should only allow edit access to authors of the document.
23+
- Do not create the document from a corporate G Suite account. If you want to edit from a corporate G Suite account then first create the document from a personal Google account and grant edit access to your corporate G Suite account.
24+
- Comment access should be granted explicitly to [[email protected]](https://groups.google.com/d/forum/cadence-discussion) so that users viewing the document display under their account names rather than anonymous users.
25+
- Comment access should also be accessible by the public. Make sure this is the case by clicking "Share" and "Get shareable link" ensuring you select "Anyone with the link can comment".
26+
27+
- Once comments and revisions on the design doc wind down, there is a final discussion about the proposal.
28+
29+
- The goal of the final discussion is to reach agreement on the next step: (1) accept or (2) decline.
30+
- The discussion is expected to be resolved in a timely manner.
31+
32+
- Once the design doc is agreed upon, the author shall export the contents of the Google Doc as a Markdown document and submit a PR to add it to the proposal repository.
33+
34+
- Authors can use [gdocs2md](https://github.com/mangini/gdocs2md) to convert the document but any cleanup required must be done by hand.
35+
- The design doc should be checked in at `docs/design/XYZ-shortname.md`, where `XYZ` is the GitHub issue number and `shortname` is a short name (a few dash-separated words at most).
36+
- The design doc should be added to the list of existing proposals in `docs/design/index.md`
37+
38+
- The author (and/or other contributors) do the work as described by the "Implementation" section of the proposal.
39+
40+
---
41+
42+
This project is released under the [Apache License, Version 2.0](LICENSE).

README.md

+7-2
Original file line numberDiff line numberDiff line change
@@ -17,6 +17,7 @@ See Maxim's talk at [Data@Scale Conference](https://atscaleconference.com/videos
1717
* Build the required binaries following the instructions [here](CONTRIBUTING.md).
1818

1919
* Install and run `cassandra` locally:
20+
2021
```bash
2122
# for OS X
2223
brew install cassandra
@@ -26,11 +27,13 @@ brew install cassandra
2627
```
2728

2829
* Setup the cassandra schema:
30+
2931
```bash
3032
make install-schema
3133
```
3234

3335
* Start the service:
36+
3437
```bash
3538
./cadence-server start
3639
```
@@ -53,9 +56,11 @@ Try out [Cadence Web UI](https://github.com/uber/cadence-web) to view your workf
5356
(This is already available at localhost:8088 if you run Cadence with docker compose)
5457

5558
## Contributing
56-
We'd love your help in making Cadence great. Please review our [instructions](CONTRIBUTING.md).
59+
60+
We'd love your help in making Cadence great. Please review our [contribution guide](CONTRIBUTING.md).
61+
62+
If you'd like to propose a new feature, first join the Cadence [discussion group](https://groups.google.com/d/forum/cadence-discussion) and [Slack channel](https://join.slack.com/t/uber-cadence/shared_invite/enQtNDczNTgxMjYxNDEzLTI5Yzc5ODYwMjg1ZmI3NmRmMTU1MjQ0YzQyZDc5NzMwMmM0NjkzNDE5MmM0NzU5YTlhMmI4NzIzMDhiNzFjMDM) to start a discussion and check if there are existing design discussions. Also peruse our [design docs](docs/design/index.md) in case a feature has been designed but not yet implemented. Once you're sure the proposal is not covered elsewhere, please follow our [proposal instructions](PROPOSALS.md).
5763

5864
## License
5965

6066
MIT License, please see [LICENSE](https://github.com/uber/cadence/blob/master/LICENSE) for details.
61-
Loading
Loading
Loading
Loading
Loading

0 commit comments

Comments
 (0)