Add contributing guide - #195
Conversation
k2d222
left a comment
k2d222
left a comment
There was a problem hiding this comment.
I would add a sentence saying that anyone is welcome to contribute, and that the recommended thing to get started is to introduce yourself and chat about your proposal idea on discord. otherwise LGTM as a first pass.
d36d883 to
933fc84
Compare
|
Sounds good, I updated the text |
|
Bump @mighdoll agree to merge? |
mighdoll
left a comment
mighdoll
left a comment
There was a problem hiding this comment.
Nice to clean up our process here!
|
|
||
| Writing a full specification and getting buy-in in one go is a very challenging task. We recommend breaking it up into smaller chunks, starting with | ||
|
|
||
| 1. **Open an issue**. Describe your problem and suggest a solution. |
There was a problem hiding this comment.
two steps: one issue for problem, Mark with 'use case' tag.
There might be solutions from more than one direction over time, and it encourages people to think and document the problem before discussing the feature idea.
second step: propose a solution, perhaps that's step 3? Then create PR? Do we want solution comments on the PR or on the tracking issue? I guess the tracking issue? we should probably make that clear.
| Writing a full specification and getting buy-in in one go is a very challenging task. We recommend breaking it up into smaller chunks, starting with | ||
|
|
||
| 1. **Open an issue**. Describe your problem and suggest a solution. | ||
| 2. Create a pull request with [a **specification proposal**](./proposals/README.md). Proposals have a very low bar for being accepted and anything at this stage is still an experiment. |
There was a problem hiding this comment.
It's not stated, but I think these should be standalone docs, not spec diffs, I guess we'll have to make one or two so people have something to follow. e.g. link to the tracking issue, bug issue, author?, etc.) (that's separate from this PR, I think.)
| 2. Create a pull request with [a **specification proposal**](./proposals/README.md). Proposals have a very low bar for being accepted and anything at this stage is still an experiment. | ||
| 3. Create a tracking issue | ||
| 4. Optionally **implement it**. This is helpful in revealing hidden complexity and polishing the design. | ||
| 5. Create a pull request with **the specification** |
There was a problem hiding this comment.
spec pr after consensus. No sense scribing/debating spec text until we've got agreement.
| @@ -0,0 +1,23 @@ | |||
| # Contributing to the WESL Specification | |||
There was a problem hiding this comment.
presumably insider types should also follow this procedure, right? Or do we imagine something different
| Writing a full specification and getting buy-in in one go is a very challenging task. We recommend breaking it up into smaller chunks, starting with | ||
|
|
||
| 1. **Open an issue**. Describe your problem and suggest a solution. | ||
| 2. Create a pull request with [a **specification proposal**](./proposals/README.md). Proposals have a very low bar for being accepted and anything at this stage is still an experiment. |
There was a problem hiding this comment.
'very low' is maybe a little too low. 'low' is low enough :-).
I think the point you're trying to make is that it's a discussion draft. Also people may want to get a little feedback on the bug and proposed solution issues before bothering to write up a document with a solution.
|
|
||
| ## Specification Stages | ||
|
|
||
| Writing a full specification and getting buy-in in one go is a very challenging task. We recommend breaking it up into smaller chunks, starting with |
There was a problem hiding this comment.
eidtiorial: no need to say it's challenging to do it wrong, just say how people should do it right.
| 3. Create a tracking issue | ||
| 4. Optionally **implement it**. This is helpful in revealing hidden complexity and polishing the design. | ||
| 5. Create a pull request with **the specification** | ||
| 6. **Find consensus**, this part is quite time consuming. We recommend the previous steps to help prepare your specification for this. |
There was a problem hiding this comment.
editorial: perhaps drop the previous steps recommendation, of course they're following the instructions if they're reading this...
| 3. Create a tracking issue | ||
| 4. Optionally **implement it**. This is helpful in revealing hidden complexity and polishing the design. | ||
| 5. Create a pull request with **the specification** | ||
| 6. **Find consensus**, this part is quite time consuming. We recommend the previous steps to help prepare your specification for this. |
There was a problem hiding this comment.
perhaps add a little explanation as to why it's hard. language feature are interdependent, we aim to support features long term, we intend most features to be upstream wgsl proposals, etc. i'm handwaving, but something explanatory.
| 1. **Open an issue**. Describe your problem and suggest a solution. | ||
| 2. Create a pull request with [a **specification proposal**](./proposals/README.md). Proposals have a very low bar for being accepted and anything at this stage is still an experiment. | ||
| 3. Create a tracking issue | ||
| 4. Optionally **implement it**. This is helpful in revealing hidden complexity and polishing the design. |
There was a problem hiding this comment.
Perhaps mention fork and add an opt in flag (maybe someday also add @!experimental() or whatever we decide there)
|
|
||
| Writing a full specification and getting buy-in in one go is a very challenging task. We recommend breaking it up into smaller chunks, starting with | ||
|
|
||
| 1. **Open an issue**. Describe your problem and suggest a solution. |
There was a problem hiding this comment.
for proposing a solution, people should look at whatever doc we have on audience, WGSL compatibility, etc. https://wesl-lang.dev/spec/Designing is probably the best bet. (we might later look to restructure proposals on the web site and make s new section or something..)
3 participants
Adds a very basic contributing guide, including the specification stages that we agreed on during our last meeting.
Fix #15
Should we add a short code of conduct section to the contributing guide or should we add a separate document, similar to wgsl-analyzer/wgsl-analyzer#392 ?