Make it possible to understand all pending changes to the API spec

[pmorie]

Our current process leaves us without a single, consistent place where accepted but not released changes to the API spec are collected together. This is inconvenient for implementors trying to track all of the latest proposed changes. We should change our process to include this, and drive processes that generate docs in other repos off of stable versions. We have a couple of options:

1. Use master as the latest accepted changes to the spec, and use release branches/git tags to represent stable, released versions
2. Use master as the latest stable version, have a separate accepted branch, and have branches/git tags for prior stable versions

My own personal preference is to do (1), because this is how the vast majority of github repositories work in my experience. Our current process does not really use github in 'the github way', and I am concerned that this will discourage participation.

When I have brought this up in previous meetings of the WG, one concern in the group was ensuring that we would be able to merge only a single proposed change at a time to a release branch. Here's what I suggest:

1. Make PRs to whatever branch we choose to track accepted changes
2. If an additional change is required during implementation, make a new PR
3. Use a commit message format to tie all commits back to the issue originating the proposal they are for

When we consider a proposal ready for release, we can make a PR to the release branch with the commits associated with the issue. Note, this will require discipline and rebasing the accepted branch onto the proposed branch to work through typos / clarifications we make to the released spec / etc.

I'm agnostic on what we ultimately do here; the above is just my proposal. I do think that we should strive to:

1. Make it possible to easily read a single document and learn all of the proposed changes to the spec
2. Make it possible for newcomers to our community to collaborate with us over github in a way they are used to

[bparees]

if i understand the flow for (1) it would be:

1) PRs get made to master to propose changes/additions to the list of accepted changes 2) As PRs get accepted/merged (indicating the propose change is accepted), the master list of accepted changes grows 3) At some point some subset of changes from the list of accepted changes get plucked into a PR against a release branch. 4) Once a change graduates from accepted to released via (3) (PR is merged), it is removed from the list of accepted changes in master.

If my understanding of that flow is correct, it seems like a reasonable approach to me.

[eriknelson]

Make it possible to easily read a single document and learn all of the proposed changes to the spec

From our perspective (implementer), this would be very helpful, since it means there's one place we can follow to track impacting changes and make sure we aren't falling behind.

I'm less opinionated on process, but 1) sounds good to me.

[jmrodri]

This is definitely helpful. Option 1 is ok with me. Will all accepted items be released at a particular time or will only some of the accepted ones be included in a release? I guess this goes back to item 4 from @bparees comment. Overall I agree that something needs to be done to highlight the accepted but unreleased proposals

[duglin]

Couple of aspects to this... 1 - if we head down a path like this, I like the idea of having 'master' be the "in-flight" version of the spec, and thus having official versions be tagged, on branches. 2 - I think we need to plan for the worst. Meaning, once a proposed change is approved for inclusion into the master/in-flight branch, we need to plan on it possibly being updated on a regular basis (as we implement/test it) and for it to be full removed if we end up rejecting the proposal later on. Both of these actions need to be easy to manage. This means that merging them into "master" might be very problematic, especially if we have overlapping proposals.

Let's back up a bit...

Unlike a code-based git project, where we expect to have PRs coming in on a very regular basis, how many PRs do we realistically think we can support having "in-flight" at the same time? The higher the number the bigger the impact it'll be on the community (us and people who plan on implementing either side). I'm not suggesting that we try to limit the number of PRs - rather, I wonder if the number of open PRs will be relatively small, like around 5? If so, is it really that hard to have 5 different proposal docs/PRs for people to look at?

I do understand the nicety of having it all in one spot, but the management of it concerns me.

Another option is to not merge the PRs. Rather have a process where they're merged via some build process and made available on some web site. Kind of like a jenkins job that tests code PRs - except it grabs/merges all of them instead of just one. W.R.T. conflicts, we'd just have to define the order in which they'll be merged (ie. oldest first) and require newer PRs to rebase on the old ones. Just a thought.

[duglin]

On 4/17 call we agreed to close this issue. In particular https://github.com/openservicebrokerapi/servicebroker/pull/500 might help to address this.