How should we handle updates to website content for the development version?

[bryanwweber]

As discussed in #23, #86, Cantera/cantera#667, and Cantera/cantera#682, certain updates to Cantera/cantera will require updates to the content on the website. The question is, how should that content be shown? The options that I think have been discussed so far:

1. A separate branch in this repository to house the updates that only apply to the development edition. This could work like it does at Cantera/cantera, where the main/"default" website is stored in a branch named for the current release and ongoing work goes onto master, or master can remain the default version and new updates go onto a dev branch. This would probably result in two separate versions of the website deployed at two URLs (e.g., https://cantera.org and https://devel.cantera.org or some such).
2. Add all new materials to master, and have a special box or other mechanism to note that the material only applies to an unreleased version of Cantera. I'm not exactly sure how this would work, and it would certainly require quite a bit of maintenance to make sure that when a new release happened, everything was updated properly, but this might be able to be automated, and could serve as a neat flag on the website ("added in 2.5.0").
3. Store the related materials in a separate repository, with content on two branches (one for the current release, one for the development version). This would minimize the amount of duplication in building the website (i.e., option 1 results in two whole websites), but would require a bit more CI wrangling and would make building the website locally more annoying.

This issue refers specifically to the science, equations, supported models, and tutorials. API developer documentation is already available.

In my opinion, examples should always be shown from the current released version of Cantera, since that content should continue to work in the developer version of Cantera, while the converse is not true; in addition, advanced users who're using the development version should be able to get updated examples from their copy of the source.

A related point that I want to quote here specifically from @speth (#86 (comment)):

[We should try to avoid the case where] a new category of examples is added that breaks the web site in some way which isn't discovered until we update for the release.

To that point, examples that only use existing features (in the current stable release) should be added to the release branch in Cantera/cantera, and if this involves new categories, that should be able to be shown on the website.

[ischoegl]

@bryanwweber ... any update on this? At some point, I should probably document what was implemented in Cantera/cantera#667 . I guess it can be 'parked' in a pull request.

[bryanwweber]

@ischoegl Yes, parking it in a pull request is probably the best scenario for now

[ischoegl]

While there is the potential of merge conflicts, I believe is should be possible to merge changes into the testing branch?

[ischoegl]

While typing up #188, I realized that one way of avoiding merge conflicts would be to redirect output from main to testing.cantera.org, whereas a stable branch could hold information for cantera.org. That way, the procedure would mimic the workflow on Cantera/cantera. (the testing branch would no longer be needed.)

This is definitely a change for after 2.6 is released ...

FWIW, this corresponds to (1) at the top:

A separate branch in this repository to house the updates that only apply to the development edition. This could work like it does at Cantera/cantera, where the main/"default" website is stored in a branch named for the current release and ongoing work goes onto master, or master can remain the default version and new updates go onto a dev branch. This would probably result in two separate versions of the website deployed at two URLs (e.g., https://cantera.org and https://devel.cantera.org or some such).

with the twist that we actually already have two URL's (although it's called testing at the moment; I think it would make sense to rename to devel).

[bryanwweber]

I think this can be resolved by option 2 in the original post. We've started using the @since and .. versionadded:: directives in Doxygen and Sphinx, respectively, in Cantera/cantera. Since #209 suggests using Sphinx to generate the whole site, we can consistently use .. versionadded:: (or something similar after #211 is completed) to identify content that only applies after a particular version. This can be enforced at the time that a pull request is made to this repository to update documentation in concert with a pull request to Cantera/cantera. As such, I think this issue can be closed.