-
Notifications
You must be signed in to change notification settings - Fork 540
Specing process reasoning
This document explains the reasoning behind our spec'ing process.
First we should capture the typical scenarios and how often it happens.
| Scenario | Frequency |
|---|---|
| Devs need to see what properties to add when implementing feature | Every feature x5 |
| PM/dev needs to review the proposed property additions to the schema | Every feature |
| Feature's properties needs to be added to public schema docs | Every feature |
| Dev codes up feature, then we change the spec and dev needs to re-update their code | Some features x5 |
| We pull a feature from a release after devs have coded it up | Rarely x5 |
| We pull an already-spec-approved feature that hasn't been coded up | Rarely |
| Scenario | Easiness |
|---|---|
| Devs need to see what properties to add when implementing feature | Mostly easy (sometimes our specs are ambiguous) |
| PM/dev needs to review the proposed property additions to the schema | Medium (tough to see impact to overall schema) |
| Feature's properties needs to be added to public schema docs | Hard |
| Dev codes up feature, then we change the spec and dev needs to re-update their code | Hard |
| We pull a feature from a release after devs have coded it up | Easy |
| We pull an already-spec-approved feature that hasn't been coded up | Mostly easy (sometimes our specs are ambiguous) |
If we merge the pull request immediately after approved and don't provide tooling, it becomes really hard to see what properties were actually added for a feature.
| Scenario | Easiness |
|---|---|
| Devs need to see what properties to add when implementing feature | Very hard |
| PM/dev needs to review the proposed property additions to the schema | Easy |
| Feature's properties needs to be added to public schema docs | Easy |
| Dev codes up feature, then we change the spec and dev needs to re-update their code | Easy (keep track of commit implemented, can see diff) |
| We pull a feature from a release after devs have coded it up | Hard for PM, easy for dev |
| We pull an already-spec-approved feature that hasn't been coded up | Hard |
Same as above but we add tooling to be able to view all affected schema changes based on the feature #'s inputted into the schema
| Scenario | Easiness |
|---|---|
| Devs need to see what properties to add when implementing feature | Easy (but requires us building tooling) |
| PM/dev needs to review the proposed property additions to the schema | Easy |
| Feature's properties needs to be added to public schema docs | Easy |
| Dev codes up feature, then we change the spec and dev needs to re-update their code | Easy (keep track of commit implemented, can see diff) |
| We pull a feature from a release after devs have coded it up | Hard for PM, easy for dev |
| We pull an already-spec-approved feature that hasn't been coded up | Hard |
We keep the pull request open until all platforms have implemented it, and then we merge
| Scenario | Easiness |
|---|---|
| Devs need to see what properties to add when implementing feature | Easy |
| PM/dev needs to review the proposed property additions to the schema | Mostly easy (can't see interplay of other new features) |
| Feature's properties needs to be added to public schema docs | Easy |
| Dev codes up feature, then we change the spec and dev needs to re-update their code | Easy (keep track of commit implemented, can see diff) |
| We pull a feature from a release after devs have coded it up | Hard for PM, easy for dev |
| We pull an already-spec-approved feature that hasn't been coded up | Easy |
In addition to the previous, we add tooling so you can also see a preview of the schema changes WITH the other approved schemas
| Scenario | Easiness |
|---|---|
| Devs need to see what properties to add when implementing feature | Easy |
| PM/dev needs to review the proposed property additions to the schema | Easy |
| Feature's properties needs to be added to public schema docs | Easy |
| Dev codes up feature, then we change the spec and dev needs to re-update their code | Easy (keep track of commit implemented, can see diff) |
| We pull a feature from a release after devs have coded it up | Hard for PM, easy for dev |
| We pull an already-spec-approved feature that hasn't been coded up | Easy |
Dev opens the pull request for the feature and sees all the properties added. Straightforward and very clear.
They open the pull request and review the properties added. They can also open the pull request on the auto-generated repo that has all approved schemas in it to view the intersection of all features.
Nothing to do! Schema is already updated :)
If ALL platforms already implemented the feature, we would have merged the PR, so we would start a new PR and leave it open till the end. But then it does make it difficult to view the feature itself cohesively.
If only one platform already implemented the feature, the PR would still be open, so we would update the PR itself. Each platform tracks the PR number and commit of that PR so they can know if they go outdated?