Proposal for Read the Docs

[afsmythe]

We presently have three different versions of v5 documentation on Read the Docs (latest, vip52, release). The latest version is linked to the master Git branch, while vip52 and release are each linked to their respective git branches.

I would like to propose that we make the release RTD branch private and create a redirect to point URLs from release to latest in Read the Docs. As we continue to update the documentation build process to better serve the 5.1.2 revision, we will commit these changes to the master Git branch (which is surfaced by latest RTD branch). Updates the 5.2 revision will continue to be placed in the vip52 Git branch.

[jdmgoogle]

So after this:

latest: The most recently released version of the spec. As of today this is 5.1.2
vip52: Version 5.2

Is that correct?

[afsmythe]

The latest branch of Read the Docs has been deactivated. We currently have two versions of the documentation; release is at 5.1.2. And vip52 is version 5.2.

[jdmgoogle]

Is there anything left to do on this issue or can we close it out?

[afsmythe]

I think we need some agreement about what the docs will be once 5.2 goes live. Will the current release branch on Read the Docs point to the 5.2 github documentation and we'll create a new RTD branch (5.3, 6.0?) for future updates?

[jdmgoogle]

One other note: in README.md we need to update the link to point to the correct documentation.

Once 5.2 is released then we can add vip53; if we need to turn that into vip60 we can but for now I propose we just call it vip53.

[afsmythe]

What should the publishing process be for vip52? Should we merge this to master? Read the Docs "release" points at the master branch, so merging vip52 to master sounds like the way to go.

[jdmgoogle]

Where did we land with any proposal about which branches point where?

[afsmythe]

I think we landed on merging vip52 in to the master branch. We'd then create a new branch, vip53 or vip6 in which future (un-released) changes would then go. Does that sound sensible?

We'd still need to agree on a publish date once the new revision is implemented by data consumers (Google) and Democracy Works and VIP States.

[jdmgoogle]

SGTM.

[afsmythe]

I think we can close this Issue after the following is completed:

1. merge the specification updates related to 5.2 in to the master whichever branch points to ReadTheDocs "release" branch
2. create the next holding branch for future releases (either for 5.3 or 6.0)

I can take a look at 1, and we'll need to decide what 2 will be.

[jswiesner]

I propose we create branch vip60 as the next iteration. Anticipating #412 will be in the next release, a major version upgrade seems appropriate to me.