New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Warn users if they are using an old/different version #640

Closed
d0ugal opened this Issue Jun 18, 2015 · 7 comments

Comments

Projects
None yet
2 participants
@d0ugal
Member

d0ugal commented Jun 18, 2015

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

This comment has been minimized.

Member

d0ugal commented Feb 22, 2016

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

This comment has been minimized.

Member

d0ugal commented Feb 22, 2016

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

This comment has been minimized.

Member

waylan commented Feb 22, 2016

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

This comment has been minimized.

Member

d0ugal commented Feb 22, 2016

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

This comment has been minimized.

Member

waylan commented Feb 22, 2016

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

@d0ugal d0ugal changed the title from Warn users if they are using an old version to Warn users if they are using an old/different version Feb 26, 2016

@waylan

This comment has been minimized.

Member

waylan commented Mar 12, 2018

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

This comment has been minimized.

Member

waylan commented Apr 6, 2018

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

waylan added a commit to waylan/mkdocs that referenced this issue Apr 12, 2018

@waylan waylan closed this in #1467 Apr 12, 2018

waylan added a commit that referenced this issue Apr 12, 2018

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment