Major API change

[geoffmcl]

Issue #223 points out that using generic installed header names is not a good thing, and I do not think the 4 tidy headers need be so isolated into a tidy sub-directory like that...

So have chosen renaming -

1. renamed: include/buffio.h -> include/tidybuffio.h
2. renamed: include/platform.h -> include/tidyplatform.h

This seems a good time to issue v5.0.0.RC1

Also since this feels like an API change, not really... but seems a good time to set the major version to 5. Read Issue #221

The .RC1 extension will magically fall away, if, after a suitable test time, this proves to be a worthy candiate!

; eof

[zmwangx]

Please excuse me, but I'm kind of confused by the tagging here. So, the 5.0.0 tag really means 5.0.0rc1, which should in principle be a strictly smaller version number than 5.0.0? And does that mean 5.0.0 will be retagged if the current release candidate turns out to be somewhat problematic (I'd say retagging is a horrible idea)?

I just want to make sure the release is final before pushing to downstream packages, e.g., the one in Homebrew; we have to be extra careful since the 5 suffix has been dropped, potentially breaking all dependents (thankfully there are none in Homebrew) and user scripts, plus upstream retagging will result in a terrible mess for downstream users.

[geoffmcl]

@zmwangx, sorry I always seem to get this tagging wrong ;=() Have deleted the 5.0.0, and added a 5.0.0.RC1 pre-release tag. Hope that is the correct action... The code is stable...

Yes, with this release the 5 suffix has been dropped. This was always supposed to be very temporary, but it got extended, extended, and extended... so for sure it drifted into user scripts...

So yes, for sure Homebrew, and any other build/install scripts, need to be updated...

Just a question on the tidy-html5.rb script. I note the cmake is system "cmake", "../..", *std_cmake_args which looks fine...

But I do NOT know what is in std_cmake_args?

If you are planning to build and install a Release version, that is one where -DNDEBUG is defined to remove the asserts, this should include -DCMAKE_BUILD_TYPE=Release.

And if you want to install tidy in the usual unix /usr/include, /usr/lib, ... should also add -DCMAKE_INSTALL_PREFIX=/usr to such std_cmake_args variable... cmake often chooses some other places, like /usr/local as the default if none given.

Also, since this also includes two renamed header files, it would be a good idea if all previous versions of libtidy be uninstalled first. While there is presently no uninstall target, the contents of install_manifest.txt should contains the last install... just delete the files listed...

And even if that manifest is not available, the 2 renamed headers means all installed instances of buffio.h and platform.h should be DELETED from /usr, /usr/local, etc, ...

This is particularly important for the man page installation. Earlier versions of tidy, before the introduction of the 5 suffix, would install tidy.1 into /usr/local/share/man/man1/. Sometimes a man tidy can look in there first, and load an OLD tidy.1. This should be deleted...

Simply, $ man tidy should open a man page with the correct version, 5.0.0.RC1, at the top and bottom...

HTH, and sorry about the tag mess up...

[zmwangx]

But I do NOT know what is in std_cmake_args?

That's an array of standard CMake flags defined by Homebrew, including all of what you have described :) (The point is the flags are almost the same for every project, so why not abstract them away instead of dropping them in every build script.)

Homebrew installs tidy-html5 to locations like $(brew --prefix)/Cellar/tidy-html5/5.0.0 (where $(brew --prefix) is usually /usr/local), then symlinks to $(brew --prefix)/bin, $(brew --prefix)/include, $(brew --prefix)/lib, $(brew --prefix)/share, etc.

it would be a good idea if all previous versions of libtidy be uninstalled first.

Yes, Homebrew keeps track of all the symlinks. The nice thing about Homebrew is that it installs each package to its separate "Cellar", as I've mentioned above, so there's no need for uninstall target — in fact Makefile is not used at all for uninstallation, and no way to miss anything (unless the install scripts do not respect the specified prefix, I guess). So all symlinks will be removed when one upgrades to a new version. One can keep the old cellar, say $(brew --prefix)/Cellar/tidy-html5/4.9.35, if one'd like to, and that won't interfere with anything.

sorry about the tag mess up...

No problem at all, thanks for the clarification.

[geoffmcl]

@zmwangx, thanks for the info on std_cmake_args... and good to hear Homebrew includes a sort of uninstall... certainly storing an app in 'Cellars' is an interesting way to control what is installed and where, then a symlink in /bin... helps me understand Homebrew a little more...

Have now published some 5.0.0.RC1 binaries - http://www.htacg.org/binaries/ - ...

Unfortunately the Windows MSI and NSIS EXE Installers are quite useless at the present time. These installers are NOT really suitable for a command line app, and are usually reserved for GUI apps. How about a Tidy-GUI2, but still very much a WIP. Any help appreciated...

For Windows the best bet is the ZIP. It contains a stand-alone tidy.exe, which can be copied to any path given in your PATH environment variable, so it can be run from anywhere. Of course if also contains the 4 headers, and static and shared libraries, which can be moved to a 3rdParty directory for development.

And have a little repo Tidy Test to find and link with such an installed tidy libraries and headers... and produce tidy-test, which is actually just tidy too... This is to develop and test a FindTidy.cmake cmake find module, to propose to the cmake maintainers at some point...

TODO: Still to do is update the API docs, with doxygen, and publish... again, any help in this would be much appreciated...

[zmwangx]

Hi, again I'm somewhat confused by tagging...

Would you be kind enough to explain why we are having 5.1.7 right after 5.0.0RC1? Is 5.1.7 a stable version, i.e., can downstream packagers update to this version?

[geoffmcl]

@zmwangx, again so am I confused, hence the delay in a reply...

I did some background reading about git tagging. It seems it is nothing more than a marker for the last commit... full stop... You can even back-date a tag by saying which specific commit you want the tag attached to, like -

$ git tag -a v1.2.3 9fceb02

So when I added tag 5.1.7 I was adding a marker to hopefully the last commit to issue-228 before I commence the merging that branch back into the master branch...

So in a sense it was just a marker added to the repo for my benefit... if there is a problem with the subsequent merge I want to be able to get back to there...

However it seems you are taking this tag to mean something else, like a signal of something...

Maybe you could describe its meaning to you, maybe point to some reading, and I will try to use the tagging that suits you, and other downstream package managers...

Maybe we could use two tag forms, say an i5.1.8 meaning internal tag, and say v5.1.9 as an indication to downstream packages that this is a stable point to take note of... or something like that...

As indicated here and in other comments actual releases are already stored in a branch, like release/5.0.0. Using a branch seems the only way to fully isolate a specific block of code...

So, to me, 'tags' are more just like a time and place marker... they just mark at a specific commit point, and do not take account of the branches... but maybe I do not understand something here...

And to repeat, the aim it to always make sure the master branch is stable...

And each version increment, in version.txt, represents a bug or feature fix, improvement, whether I remember or not to add a tag as well...

And it is hope downstream packagers can take advanatage of this to offer the latest, best, soonest thereafter...

Please help me understand your tag needs...

[zmwangx]

You can even back-date a tag by saying which specific commit you want the tag attached to

So in a sense it was just a marker added to the repo for my benefit...

Yes, you certainly can tag at any moment, to any commit. However —

Maybe you could describe its meaning to you, maybe point to some reading, and I will try to use the tagging that suits you, and other downstream package managers...

I'm not sure if it's documented anywhere, but for most projects (or so I believe) it is a convention that tags are used to indicate releases. And once a tag is made it should never change, because people will use the tag to check out the specific release (say git checkout v5.0.0), or download the tarball at the specific tag and verify that its checksum is the same as documented somewhere. See https://github.com/Homebrew/homebrew/blob/master/Library/Formula/tidy-html5.rb#L4-L5, for instance, where the 4.9.35 tag is used in Homebrew as the latest release, and we have a checksum for the tarball.

You may have a look at https://github.com/git/git/releases or https://github.com/torvalds/linux/releases. They use v-prefixed tags; some projects prefer that, some projects don't.

As indicated here and in other comments actual releases are already stored in a branch, like release/5.0.0. Using a branch seems the only way to fully isolate a specific block of code...

Yes, but I wonder if it is really necessary that 5.0.0 be completely isolated? I think for most projects all releases are first cut at some point of the master branch (as you have seen in git.git and linux.git), and then some may also maintain some older stable branches for backporting bug fixes (take linux-stable.git as an example: https://git.kernel.org/cgit/linux/kernel/git/stable/linux-stable.git/). But since 5.0.0 isn't even released yet — certainly no backporting talk yet (I suppose?), so maybe it's enough to keep things on master?

Anyway, I think it's okay to have a release/5.0.0 branch, but most projects just cut releases on master, and a tag with a version number is certainly suspicious to at least some of us...

So, to me, 'tags' are more just like a time and place marker... they just mark at a specific commit point, and do not take account of the branches... but maybe I do not understand something here...

And to repeat, the aim it to always make sure the master branch is stable...

master being stable is great, but I think it's still good to have release tags, otherwise packaging will be a nightmare, because we can't update a downstream package with every commit.

And each version increment, in version.txt, represents a bug or feature fix, improvement, whether I remember or not to add a tag as well...

Am I right in thinking (according to https://github.com/htacg/tidy-html5/blob/release/5.0.0/verhist.log), that 1e70fc6 is version 5.0.0? However, the release tag says 5.0.0.RC1, so it's still very confusing... Version 5.0.0 is certainly to be packaged, but 5.0.0.RC1 is certainly not...

[zmwangx]

Actually I found a GitHub blog post that vaguely points to the convention I was talking about. From https://github.com/blog/1547-release-your-software:

Following the conventions of many Git projects, releases are tied to Git tags. You can use an existing tag, or let releases create the tag when it's published.

We recommend projects use Semantic Versioning, but it is not required.

Maybe there are more elaborate writings on the convention I described, but I can't find them at the moment.

[geoffmcl]

@zmwangx thanks for the link...

First, it is intended that Tidy does generally follows Semantic Versioning...

And yes, it seems github docs inexplicably link Releases with tags... in that the Releases link is actually just a list of tags...

But you can see the important tags are marked with a colored left label, while others are just listed bare...

I need to experiment to get to understand what github wants, expects us to do to mark a release...

And this reminded me I must get around to doing two other things -

1. Remove the .RC1 from the 5.0.0 and declare it an official release, and
2. Merge the issue-228 branch back to master, when I will bump the version to 5.1.8

Then maybe move that green Latest Release label to it, 5.1.8... as the latest and best release...

And maybe it is time to consider a 5.2.0 release soon... when master would move on to 5.3.0...

Hope to get this right eventually ;=))

[zmwangx]

But you can see the important tags are marked with a colored left label, while others are just listed bare...

In fact, tags marked with a colored left label are those for which you bother to write release notes and/or add artifacts on the GitHub end. Those are not part of the repo — they just make distribution on GitHub easier.

Remove the .RC1 from the 5.0.0 and declare it an official release

I think it might be better to tag the same commit as 5.0.0 (you are certainly allowed to do that), if you decide that there's no problem with that commit? Because I believe the consensus is that deleting an already pushed tag could cause similar trouble to people who have cloned the repo as force updating history (RC releases are less important in the long run and it's unlikely that people will check them out after stable, but anyway, git is supposed to keep the entire history of projects).

Anyway, you're the maintainer so you'll get to decide whether you want to follow community wisdoms or not; but can we just establish a policy that makes downstream packaging easier? Say, can we agree that you'll use GitHub's "Draft a new release" feature for "important tags", so that when we see a non-pre-release tag with colored left label, we are confident that we can update the downstream package?

By the way, this is not only for packaging's sake: I personally use the project in some CI's — very helpful by the way, thanks a million — and while you try to make master stable all the time, occasionally it does suffer some backwards incompatible changes (e.g., the 5 suffix being removed), so I'm much more confident about checking out a release tag (and knowing that it'll never change or vanish).

[zmwangx]

Oh, I just saw 5.0.0 with its green label. Nice!

[geoffmcl]

@zmwangx as you point out unfortunately it seems those labels are added by github... At least so far I have not found to way to fully control them... it depends on using the Draft a new release, and then Publishing it with comments, and artifacts...

I just added a tag for 5.1.8, the final merge of the issue-228 branch back into master, and I am sure that green label will move if I take the publishing step... not exactly what I would prefer...

But on the other hand, as you point out, maybe that is ok...

Since I do feel 5.1.8 is a stable, and good step forward with -

• new feature --vertical-spaces auto, with --wrap 0, --indent no, which outputs the html as a single compact html line,
• new feature --indent-with-tabs yes, maybe --indent-spaces 1, which becomes a tab count instead of spaces,
• fix some newline problems with a pre element, and
• some other good fixes... see 5.1.8 Release Notes for details...

it is worthy of being published as a release, and let the Latest release label moved to it...

Will leave that decision for a little time for some more testing by everyone pulling master...

Thanks for helping me get my head around this tagging idea ;=)) As you suggest, I will try to publish important tags, thus urging downstream packages to do an update.

Anyway, this Major API change Infrastructure issue has sort of run its course, so will close it...