Define the versioning model for the SSL Config Generator

[gene1wood]

(This issue came out of #240 (comment) )

The SSL Config Generator has essentially 2 different "versions" that might matter. One is the version of the guidelines, which is what the guideline argument in the permalink is for and is meant to map to the version of the recommendation, which the SSL Config Generator is trying to use as it's basis for rendering configurations. This version can be seen in https://wiki.mozilla.org/Security/Server_Side_TLS#Version_History .

The second is the version of the SSL Config Generator itself. This would be changes to how the generator functions or changes to specific configuration logic based on changes to server software. We don't really track this version and I'm seeing that we're kind of conflating the two versions (for example with this 5.7.1 release which captures new SSL Config Generator functionality but which doesn't relate to a change in the actual guidelines that sit behind the generator.

This can also be seen in the Unreleased section of the CHANGELOG which shows changes that are live on the SSL Config Generator site (and not unreleased). These changes don't have a version to go into since they're not a change to the guidelines.

The CHANGELOG was originally meant to be a CHANGELOG for the guidelines (which is why it's in the src/static/guidelines directory instead of the root) but it now contains changes for both the generator and the guidelines. Once we figure this out we should separate the CHANGELOG into guidelines and generator changelogs.

This dual/conflated versioning is confusing and we should probably do something to clarify this. Maybe we do reserve the patch portion of the semver for changes to the generator and restrict the guidelines to only using major and minor. This would follow the 5.7.1 release example.

What do folks think?

• Should we reserve the patch part of the semver for changes to the SSL Config Generator?
• Should the SSL Config Generator have it's own distinct version number, unrelated to the guidelines version? If so how do we make sure that there's no confusion between the two versions? Start at version 100.0.0?
• Is there some better way to track changes to the config generator and the guidelines distinctly?

[gstrauss]

While I am a big fan of VCS, I question the need of whether or not to have public releases of the ssl-config-generator, a client-side javascript application. Picture it this way: I do not think we will put out a news release for a new version of ssl-config-generator, where we might want to generate some tech buzz for a new release of the guidelines, which absolutely should be versioned.

If the ssl-config-generator ever grew a "raw" option for scripts to call and directly consume the generated output, then versioning would be more strongly indicated. As is, there are places in most configs which require the user to manually replace "/path/to/something"; some of the generated configs require various manual editing before the config can be used on a visitor's system. Should we replace those items with documented syntax for programmatic replacement? %STAPLING_FILE_PATH% %PRIVATE_KEY% %CERT_CHAIN%? All of that would require some design and, preferably, input from anyone currently using a script to scrape the site and parse the HTML.

In short, I think we should continue to version the guidelines, but I do not think we should publicly version the ssl-config-generator client-side javascript application. I would consider more formally creating versioned releases of the ssl-config-generator if multiple external users made such a request and shared their usage scenarios. In that case, we would develop a release procedure and would probably want to stop publishing to github pages automatically upon commit to the master branch.

• Should the SSL Config Generator have it's own distinct version number, unrelated to the guidelines version?
• Is there some better way to track changes to the config generator and the guidelines distinctly?

Yes. The guideline version is in the URL. The git short-commit SHA is on the bottom right of the generated page. We might choose to include one or both in the URL. Similar to the recent changes I made for #240, I also mocked up a change to add buildrev=... to the URL with the git short-commit SHA. It is only a few lines of code. However, the buildrev is only informational -- it does not trigger a rebuild or re-render the site for a different buildrev; only the current buildrev reflects the code used to render the site. This is yet another reason to keep the guideline version separate.