Re: Making a public snapshot from the GitHub repo

Hi Frans-

A good start ... although I have a few suggestions :-)

1) it is better to use a top-level directory for the snapshots (e.g.
/publishing-snapshots rather than /UseCases/snapshots) - just makes life
simpler knowing that /UseCases only contains current stuff

2) when creating a snapshot, I would recommend creating a new sub-directory
for each snapshot- in this way you can be sure that all the resources
required for that snapshot are the consistent ... so for example, imagine
that the FPWD publication is today (W3C only publish on Tue and Thu), I
might create the directory /publishing-snapshots/FPWD-2015-06-11-UseCases/

... Given that every snapshot is in it's own unique directory, then the
html file itself can have a much simpler name. In CSVW we use Overview.html
because that's the name of the file generated by Respec... and they all end
up as index.html when published to w3.org anyway.

3) You need to change the document status; you do this (along with
specifying the publication date) by adding some query params to the doc URL
that Respec interprets - so, once more assuming publication is next
Tuesday, I might request the URL:
http://w3c.github.io/sdw/UseCases/SDWUseCasesAndRequirements.html?specStatus=FPWD;publishDate=2015-06-11

... at this point, Respec is not showing any warnings, so we can continue
to create the snapshot using the Respec button; "Save Snapshot" then "Save
as HTML" (I think you did this anyway) and saving the resulting
(self-contained) HTML file to disk. Respec always calls this Overview.html.

... I've added /publishing-snapshots/FPWD-2015-06-11-UseCases/Overview.html
to the jtandy-uc-edit branch so that I can go on to check the W3C pub rules
and hyperlinks.

... because I'm not publishing in gh-pages (you normally would) I have to
use "rawgit" [1] (which uses the URL of the resource in the github repo) to
render the html ... in my case, the dev/test URL for the resource

https://github.com/w3c/sdw/blob/jtandy-uc-edit/publishing-snapshots/FPWD-2015-06-11-UseCases/Overview.html

is:

https://rawgit.com/w3c/sdw/jtandy-uc-edit/publishing-snapshots/FPWD-2015-06-11-UseCases/Overview.html

4) Now check pub-rules and hyper links.
... check  the W3C pub-rules using the checker service [2].

... in this case, there were 4 HTML validation errors caused by <li>
elements not being wrapped in a <ul> or <ol> ... I've fixed these in the
jtandy-uc-edit branch. I also replaced a few "&" characters with "&amp;".
Having fixed these & committed the changes, I generated a new snapshot as
above and retested ...

... there are some other errors too- but because this is being publishing
jointly, I'm not sure what constraints we have. That's one for @PhilA to
resolve!

... and finally use the W3C link checker service [3].

... again, there are some errors because we're not publishing in the final
location. There are also a number of redirects (HTTP 301 status) that are
reported; we may want to directly point to the target of the redirect. The
HTTP 500 status responses actually resolve OK when you use a browser.

... I fixed a couple of broken fragment links & republished.

5) We can skip the steps about adding references to previous versions and a
diff because this is FPWD.

So we now have a FPWD publication (albeit for today's date- this will have
to change once W3C give us the _proper_ date). FWIW, I've created a PR [4]
with the snapshot and fixes.

... note that commit f7bb9f4
<https://github.com/w3c/sdw/commit/f7bb9f41e01f05a2708bac173b74a8e26fccb496>
[5]
deletes your old snapshot directory and commit c24373e
<https://github.com/w3c/sdw/commit/c24373ebe52fe8c0b0392a8f4c66b561b0e6a832>
[6] involves
removal of a fragment ref for a related requirement that I couldn't find
existed anymore (#PositioningSystem). If that was wrong, you can always
Revert a specific commit and push to the jtandy-uc-edit branch on w3c/sdw.

Hope that helps ...

Jeremy

[1]: https://rawgit.com
[2]: http://www.w3.org/2005/07/pubrules
[3]: http://validator.w3.org/checklink
[4]: https://github.com/w3c/sdw/pull/7
[5]:
https://github.com/w3c/sdw/commit/f7bb9f41e01f05a2708bac173b74a8e26fccb496
[6]:
https://github.com/w3c/sdw/commit/c24373ebe52fe8c0b0392a8f4c66b561b0e6a832

On Wed, 10 Jun 2015 at 17:49 Frans Knibbe <frans.knibbe@geodan.nl> wrote:

> Hello Jeremy,
>
> Thank you. I took the liberty of following a condensed procedure: I made a
> 'snapshots' folder in the GitHub repo, downloaded a snapshot via ReSpec and
> put the snapshot in the snapshots folder. Do you think I missed any really
> important steps that way?
>
> Regards,
> Frans
>
> 2015-06-10 16:03 GMT+02:00 Jeremy Tandy <jeremy.tandy@gmail.com>:
>
>> Frans, Alejandro ...
>>
>> in the CSV on the Web WG, we have developed a process [1] for creating
>> snapshots. You'll see in the CSV wg Github repo that we have a "publishing
>> -snapshots" directory [2] where the frozen snapshots get put.
>>
>> Happy to talk you through this ... please let me know when suits, but
>> note that I will be travelling from Tue 16-Jun.
>>
>> Jeremy
>>
>> [1]: https://github.com/w3c/csvw/blob/gh-pages/publishing_process.md
>> [2]: https://github.com/w3c/csvw/tree/gh-pages/publishing-snapshots
>>
>
>
>
> --
> Frans Knibbe
> Geodan
> President Kennedylaan 1
> 1079 MB Amsterdam (NL)
>
> T +31 (0)20 - 5711 347
> E frans.knibbe@geodan.nl
> www.geodan.nl
> disclaimer <http://www.geodan.nl/disclaimer>
>
>