Warn users if they are using an old/different version

[d0ugal]

pip has a nice feature where they warn users if they are using an old version and prompt them to update. I think it would be neat to add something like this. The code they use for it is here: https://github.com/pypa/pip/blob/7.0.3/pip/utils/outdated.py#L95

[d0ugal]

I actually think this is becoming more important. Otherwise multiple users could end up deploying the same docs with different MkDocs versions.

For example, Alice is working on Project X and installed MkDocs six months ago. Then Bob joins the project and installs MkDocs today when he wants to deploy the documentation, he gets a more recent version than Alice did. Now when they deploy the documentation, the deployed docs will switch between the old and new version - possibly adding or removing bugs and features.

[d0ugal]

Given that we include the MkDocs version in the git commit message we could use that information to warn about using older versions than a previous deploy.

[waylan]

Ah, so you are suggesting that the gh-deploy command check the gh-pages branch for the latest commit, extract the MkDocs version from the commit message, do a version comparison with the currently installed version of MkDocs, and issue a warning if they don't match? That might work.

What happens when doth Alice and Bob upgrade? Should they still get the warning the first time they deploy? Or should the warning only issue for Alice before she upgrades? In order words, should we allow newer versions to deploy silently but warn on older versions, or should we always warn on mismatched versions? This is what is not clear to me.

[d0ugal]

In order words, should we allow newer versions to deploy silently but warn on older versions, or should we always warn on mismatched versions? This is what is not clear to me.

Good question. I am not sure. I am not sure I even like the idea in general. I guess we should allow newer versions - otherwise that could be annoying. Although, if it is just a warning, that would be fine.

So, how about:

• If it is an older version, error with a flag to do it anyway.
• It it is a newer version, display a warning/info message "The previous deploy was done with MkDocs version X you are deploying with version Y"
• If it is the same version, don't do anything.

[waylan]

That works for me. I like the "info" message on a newer version.

[waylan]

One problem with the proposal is that the "message" is configurable. Yes, the default message includes the MkDocs version, but users can override that with anything they want. I suppose this could be configured to only work if a version string is found in the message (if the previous commit does not include a version, then skip the check). Then we could warn users that if they want the check to be performed then their custom messages needs to conform to some pattern. We already call message.format() on the message passing in the sha and version, so that could all be addressed via documentation.

[waylan]

For the record, a few ways to get the most recent message are:

git log --format=%s -n 1
git show -s --format=%s HEAD

git log --format=%B -n 1
git show -s --format=%B HEAD

With format=%B the entire message is returned, while format=%s returns the first line only. Apparently %B is a more recent addition and not available on older git versions. As for show vs. log, show only ever references one object while log returns a list which is limited to the first item with -n 1.

Note that git rev-list --format=%s --max-count=1 HEAD (as well as its %B counterpart) also works, but rev-list includes the commit SHA, whereas log and show only output the message by itself.

To reference a branch other than the branch of the working tree, use refs/heads/<branchname>. Using only <branchname> could cause a conflict if another object has the same name (perhaps a tag or directory?). Prefixing with refs/heads bypasses those other objects. See gitrevisions) for details. Being able to access a branch other than the current branch also appears to remove the option of using the log command. Therefore, the correct command appears to be:

git show -s --format=%s refs/heads/gh-pages