search

yaml / yaml-spec

YAML Specification
http://yaml.org/spec/
348 stars 53 forks source link

Please provide git tags or branch heads at history points that were released spec versions #172

Closed jcflack closed 3 years ago

jcflack commented 3 years ago

Hi,

I noticed updates to the web specs today, such that the former URL spec/1.2/ now gets meta-refreshed to spec/1.2.1/, and the old one can only be reached as spec/1.2.0/, and in each version there is an errata link that leads to a 404, and here in the git history there do not seem to be any branches or tags that definitively mark the points in development that correspond to the 1.2.0 and 1.2.1 spec versions. If there were, I would be happily using git tools to figure out exactly what has changed in the spec.

I am currently going through a diff of the two HTML pages, but that is rather noisy because of all the generated node IDs being different.

git tags pointing to the versions that became the published spec releases would be very helpful.

... although not exactly the same issue, I should mention that the meta refresh style of redirect loses any fragment identifier from the original URL, so anybody trying to follow a link from elsewhere such as https://yaml.org/spec/1.2/#ns-tag-char just ends up at the top of the page rather than the intended element.

perlpunk commented 3 years ago

The meta refresh will probably be changed back to the original page because it loses the url fragment.

Note that the previous spec/1.2/spec.html was actually number 1.2.1 because it was edited three months after being released, so with the new locations /1.2.0 and /1.2.1 we are keeping the past versions available.

Please let us know if you find more 404, thanks!

jcflack commented 3 years ago

Thanks! Another option to the meta-refresh business might be to serve a page with a bit of JavaScript that loads the new URL, keeping the fragment identifier.

I am glad to have past versions available, but what is even better than having past versions is being able to explore the exact changes between the versions. Errata files (when they aren't 404 :)), changelog files, those are ok. Kind of the gold standard would be the ability to review the git commits between positively identified history points.

ingydotnet commented 3 years ago

@jcflack this issue belongs on https://github.com/yaml/www.yaml.org

The spec sources now live in this repo. The www.yaml.org build system (make build) set them up to be published there.

The https://github.com/yaml/www.yaml.org/tree/gh-pages-2021-08-21 tag shows the where the repo was a couple months ago when gh-pages was the primary branch. We made the main the primary starting at that point.

Sorry about the dust. We moved a lot of stuff around this past weekend. Still sorting things out.

Like @perlpunk said, let us know what you find.

PS We hang out at https://matrix.to/#/#chat:yaml.io if you want to chat..

ingydotnet commented 3 years ago

Fixed https://yaml.org/spec/1.2/spec.html and https://yaml.org/spec/1.2/

Also fixed the 1.2/errata.html page.

ingydotnet commented 3 years ago

FWIW this repo is tagged https://github.com/yaml/yaml-spec/tree/1.2.2 for the new 1.2.2 spec revision.

If you want to bring up the meta refresh topic https://github.com/yaml/www.yaml.org please do.

Closing this for now.

perlpunk commented 3 years ago

I opened https://github.com/yaml/www.yaml.org/issues/92