future and latest branches?

[rjleveque]

I created a new branch v5.5.0_future which I just pushed to this repository. I also rebuilt the docs so that v5.5.0_future now appears in the list of versions on the menu to the left of each doc page, so it's possible to allow everyone to view the future documentation this way, while the main landing page for the docs is still master, which we should keep up to date with the current release (v5.4.1 at the moment).

For example, the file http://www.clawpack.org/topo.html shows the current v5.4.1 documentation but if you select v5.5.0_future you will see the future version.

I suggest that going forward we might maintain a branch called future (if we're not yet sure whether the next release will be a major or minor release) and do PRs to that branch if we're adding documentation for things not yet in the latest release.

Also, perhaps we should rename master to latest so that in the menu this shows up as latest to avoid possible confusion (since currently master in the doc repo refers to the latest release whereas master in all other repos contains future stuff).

Comments welcome, particularly from @mandli and @ketch since we are the primary updaters of the docs.

[ketch]

That sounds good; thanks for starting to set it up!

[ketch]

To be clear, I also favor renaming master to latest for the docs repo.

But I would favor something like "dev" instead of "future", unless "future" is widely accepted. I think numpy and matplotlib currently use "devdocs". To me "future" is confusing because it's documentation of the current state of the master branch (though I understand that the implied meaning is "future release").

[mandli]

This sounds good to me and naming the branch dev or devdocs is fine with me. Is there a way to control the order of those versions though?

[rjleveque]

That sounds fine to me too. Maybe just "dev"?

[rjleveque]

I just implemented something like what was discussed above, now live at http://www.clawpack.org/contents.html

• There is no longer a master branch and there is a new v5.5.0 branch that is set to be the default branch for new PRs.

• To update the documentation that applies to the released code (or other general documentation added), do a PR to the v5.5.0 branch. This will also be the default branch when building the documentation as the landing page for www.clawpack.org.

• There is a new branch dev. Do a PR on this branch if you are adding documentation for new features that have been merged into the master branch of some code repository but are not in the current release.

• When changes to the current docs are merged into v5.5.0, they should generally also be merged into dev.

• When it is time to release the next version (say 5.5.1), the following procedure will keep this system going, I think...

  1. checkout dev and create a new branch v5.5.1 off of this.
  2. keep the v5.5.0 branch around for use in building docs with past versions using sphinx-versioning (other old versions are tags rather than branches, but either should work).
  3. continue developing on the v5.5.1 and dev branches.
  4. follow http://www.clawpack.org/howto_release.html#updating-the-documentation to update pages such as changes_to_master.rst and to create a new release_5_5_1.rst page.

There are various other places where specific releases are cited in the doc's and should be updated, I'm still tracking some of those down.

[mandli]

This all looks good to me. I especially like being very explicit with what goes where and what everything means. If this does seem to work we should collect this in a spot where we have other release direction and/or in the wiki for this repository.

[rjleveque]

Yes, I'll add this to http://www.clawpack.org/howto_doc.html once it's working smoothly.