search

gridcf / gct-docs

Grid Community Toolkit documentation
http://gridcf.org/gct-docs/
1 stars 4 forks source link

Updated docs for gct 6.2 #5

Closed fscheiner closed 5 years ago

fscheiner commented 5 years ago

As we released GCT 6.2 a while ago, we should now also have the documentation reflect the 6.2 release. This PR makes the respective changes. Please have a look.

fscheiner commented 5 years ago

Addendum:

I wanted to perform this update before changing to versioned docs, as (1) we need updated docs for our users now and (2) the change to versioned docs will require additional things anyhow, because we are already using documentation links that point to files directly below [...]/gct-docs/, so can't go to versioned subdirs directly as imagined before. Therefore I thought about putting all documentation in a different "root" dir (i.e. gct instead of gct-docs on gridcf.org) and let a redirect (or better a rewrite rule) for gridcf.org/gct-docs always point to the latest version of the docs (i.e. gridcf.org/gct/latest/), so our existing documentation links continue to work but always point to the latest release.

The result will look like this example:

gridcf.org
├── gct
│   ├── 6.2
│   └── latest -> 6.2 (symlink)
└── gct-docs -> gridcf.org/gct/latest (rewrite rule)

What do you think?

fscheiner commented 5 years ago

@matyasselmeci

  • There are a couple of places, e.g. ccommonlib/C_Common_Libraries_Change_Summary_Frag.adoc where you replaced the contents of a section with * None. Should we just delete those sections entirely or comment them out to keep them as a reminder?

I actually thought about moving some of these changes to e.g. the feature list, but I think they don't fit in there. E.g.:

* Update of build system to enable parallel builds, cross-compiling, and easier
  testing
* Port of build system to Mac OS X and Windows

...is nice to have, but not really a feature of a toolkit part, I'd say. And in addition we still have the information in the history and for the versioned docs we can also later re-instantiate a copy of the repo at 0367ea45f760d5d3382d27a623d391751e1f954a as historic documentation for GCT/GT 6.0.

  • There are a couple of places, e.g. gridftp/GridFTP_Change_Summary_Highlights_Frag.adoc where you removed lists of changes (because they were between 5.2 and 6.0?). It might be worth keeping that information, perhaps by putting it in sections like "Changes between GT 5.2 and GT 6.0"?

Well, here I tried to follow what we already have in the files. And when there was no section for changes between prior releases (i.e. smaller than 5.2) or from prior releases to other prior releases, I also didn't move the changes between 5.2 and 6.0 to a separate section, but just omitted them.

That's a good idea. The "GT JIRA Archive" is now also available from the Wayback Machine and from archive.is. Sadly I couldn't find a similar archive for the gridftp tickets, for example for this one:

* http://jira.globus.org/browse/GRIDFTP-178[GRIDFTP-178]: Hanging server processes with GT5.0.4 striped GridFTP servers

...although I believe that's the only one from thate "queue" and I actually don't know the status of it without the context. UPDATE: _I checked some GridFTP advisories I created for PRACE and I referenced this specific ticket in another ticket (GT-516) which is considered resolved. But I'm unsure if this already justfies the removal of this issue from the list of known problems, because the Globus developers still kept it for the GT6.0 release documentation._

msalle commented 5 years ago 
* Update of build system to enable parallel builds, cross-compiling, and easier testing
* Port of build system to Mac OS X and Windows

...is nice to have, but not really a feature of a toolkit part, I'd say.

Well, considering that we also produce the installer source tarball, I'd say it's certainly a feature. It's irrelevant if you use debs or rpms, but then it's also not really the toolkit?

And in addition we still have the information in the history and for the versioned docs we can also later re-instantiate a copy of the repo at 0367ea4 as historic documentation for GCT/GT 6.0.

How about making a tag for that? That's easier to find back

  • There are a couple of places, e.g. gridftp/GridFTP_Change_Summary_Highlights_Frag.adoc where you removed lists of changes (because they were between 5.2 and 6.0?). It might be worth keeping that information, perhaps by putting it in sections like "Changes between GT 5.2 and GT 6.0"?

Well, here I tried to follow what we already have in the files. And when there was no section for changes between prior releases (i.e. smaller than 5.2) or from prior releases to other prior releases, I also didn't move the changes between 5.2 and 6.0 to a separate section, but just omitted them.

I think a different page/section with historic changes would be good (as Matyas suggests). If you try to find back when something was fixed (or broken) it's good to have.

That's a good idea. The "GT JIRA Archive" is now also available from the Wayback Machine and from archive.is. Sadly I couldn't find a similar archive for the gridftp tickets, for example for this one:

* http://jira.globus.org/browse/GRIDFTP-178[GRIDFTP-178]: Hanging server processes with GT5.0.4 striped GridFTP servers

I got a redirect to https://www.globus.org/jira.globus.org which links to https://docs.globus.org/gt-jira-archive/ (as you also mentioned below). That page would be good to mirror I guess.

...although I believe that's the only one from thate "queue" and I actually don't know the status of it without the context. UPDATE: _I checked some GridFTP advisories I created for PRACE and I referenced this specific ticket in another ticket (GT-516) which is considered resolved. But I'm unsure if this already justfies the removal of this issue from the list of known problems, because the Globus developers still kept it for the GT6.0 release documentation._

fscheiner commented 5 years ago

@matyasselmeci @msalle One of the problems I have with the history sections is that I don't always know if information was not just still listed because of carelessness. E.g. this known problem from 4afb016bf34876b07a112cb15cf70d5683f70f13/gridftp/GridFTP_Known_Problems_Frag.adoc:

* http://jira.globus.org/browse/GT-318[GT-318]: globus-url-copy (guc) and "-do" option inconsistency

...was resolved on 2014-01-22 but the release of GT6.0 was on 2014-09-11 and it was still listed in the GT6.0 documentation. To "clean" this up would require a lot of work for cross-checking with available information to clarify for which release that problem was still present - if at all possible to find out or limit to a specific release - and as said, I plan to re-instantiate a copy of the GCT/TG6.0 docs anyhow, so that information is not lost at all.

A correction for the tag: we should actually tag the merge commit 4afb016bf34876b07a112cb15cf70d5683f70f13 I assume, instead of 0367ea45f760d5d3382d27a623d391751e1f954a as proposed by me earlier. How should we do that? I'm a little afraid of pushing to upstream from my fork directly. Maybe an unnamed release could do the job? My proposal for the tag is GCT/GT6.0, the next one could be GCT6.2

msalle commented 5 years ago

Hi, I agree that old pages with Known Problems are tricky. I would mainly be interested in (and that was also what Matyas suggested) old release notes/changelogs. Those don't need updating but are good to have.

Concerning a tag, I would probably just tag on the upstream branch. Not sure how you could otherwise do that... You could make it a pre-release?

fscheiner commented 5 years ago

@msalle @matyasselmeci I'll comment on a few files as I think I require some examples. :-)

fscheiner commented 5 years ago

bump

fscheiner commented 5 years ago

@msalle @matyasselmeci Can we merge my changes, so we finally serve a 6.2 based documentation? I can then start with implementing the changes for the planned versioned documentation.