inconsistency & errors in Bullseye to Chimaera migration documentation #4

Closed
opened 6 months ago by auanta · 5 comments
auanta commented 6 months ago

The following issues were found with Bullseye to Chimaera migration documentation:

  1. The (as of the time of writing) currently online website documentation does not correspond with the git repo documentation
  2. The provided script at the bottom of the live webpage does not correspond with neither the aforementioned webpage itself nor the git repo doc, as for example it uses certain apt commands that are not mentioned at all in either.

--> Solution: Make the migration steps all the same for this version of Debian, including the script.

  1. The currently online webpage documentation for this version has been found to be non-working, leading to somewhat catastrophic migration experiences (thread here).

  2. The git repo doc detailing the migration to Chimaera references only Stretch and Beowulf. It is unclear whether this is the correct documentation.

--> Solution: Identify and verify correct migration documentation intended for this version. Someone on the team (a programmer) who knows what steps should go into the docs for a smooth migration, and some volunteers to test it (I will volunteer).

The following issues were found with Bullseye to Chimaera migration documentation: 1. The (as of the time of writing) currently online [website documentation](https://www.devuan.org/os/documentation/install-guides/chimaera/bullseye-to-chimaera) does not correspond with the [git repo documentation](https://git.devuan.org/devuan/documentation/src/branch/master/install-guides/chimaera/bullseye-to-chimaera.md) 2. The provided script at the bottom of the live webpage does not correspond with neither the aforementioned webpage itself nor the git repo doc, as for example it uses certain apt commands that are not mentioned at all in either. --> Solution: Make the migration steps all the same for this version of Debian, including the script. 3. The currently online webpage documentation for this version has been found to be non-working, leading to somewhat catastrophic migration experiences ([thread here](https://dev1galaxy.org/viewtopic.php?id=5147&p=2)). 4. The git repo doc detailing the migration to Chimaera references only Stretch and Beowulf. It is unclear whether this is the correct documentation. --> Solution: Identify and verify correct migration documentation intended for this version. Someone on the team (a programmer) who knows what steps should go into the docs for a smooth migration, and some volunteers to test it (I will volunteer).
Poster

First of all I was made aware that the documentation (in its html version) also lives at https://git.devuan.org/devuan/www.devuan.org/src/branch/new-beta/source/os/documentation/install-guides/chimaera/bullseye-to-chimaera.html

So it appears what has happened here is data from the documentation editing repo did not make it into the web source code.

I do understand the concept behind separating the html source from the markdown documentation texts, it makes it easier for editors to find and work with the text directly.

It seems the html source code was autogenerated by HTML Tidy (a web app...).

These commits show the sequence of events
https://git.devuan.org/devuan/documentation/commits/branch/master/install-guides/chimaera/bullseye-to-chimaera.md
https://git.devuan.org/devuan/www.devuan.org/commits/branch/new-beta/source/os/documentation/install-guides/chimaera/bullseye-to-chimaera.html

I'd recommend LibreOffice to generate html instead, just copy the stuff from the markdown, paste into LibreOffice and save as HTML, then push it up to git. It's not a beautiful solution but it works and should only take a minute. (You can even convert to mediawiki format, wink wink nudge..jk)

@tomasz on the forums is having trouble accessing this git web interface so I will share his comments:

https://dev1galaxy.org/post.php?tid=5147&qid=36878

"I've inspected the situation around this process and there are many things that I don't understand or think need fixing. I'll address only two now."

  1. "First of all, it's not clear, why there are two repositories for documentation. Does the first one have any stand-alone purpose? Does it have to exist at all? With just one repository, there would be fewer integration problems. I'd just operate in the MD format (which can be simply plain text if clarity is preferred) and shift translation to HTML further in the build process. The HTML files are just artefacts. Of course there's a point in archiving them, but I wouldn't version them this way. A CI/CD line should take care of this.

  2. "The documentation repository as it stands now would benefit from a clear licensing info. I see such notes in various files, but it's unclear in general, for the whole repo. Compare with the website repo, where this is explicit at the very top of the tree. The shell script linked in the migration instruction is simply unlicensed. A single SPDX line would do. But README.adoc also needs this info."

So, in total there are 6 issues which I have numbered to make it easy to follow.

First of all I was made aware that the documentation (in its html version) also lives at https://git.devuan.org/devuan/www.devuan.org/src/branch/new-beta/source/os/documentation/install-guides/chimaera/bullseye-to-chimaera.html So it appears what has happened here is data from the documentation editing repo did not make it into the web source code. I do understand the concept behind separating the html source from the markdown documentation texts, it makes it easier for editors to find and work with the text directly. It seems the html source code was autogenerated by HTML Tidy (a web app...). These commits show the sequence of events https://git.devuan.org/devuan/documentation/commits/branch/master/install-guides/chimaera/bullseye-to-chimaera.md https://git.devuan.org/devuan/www.devuan.org/commits/branch/new-beta/source/os/documentation/install-guides/chimaera/bullseye-to-chimaera.html I'd recommend LibreOffice to generate html instead, just copy the stuff from the markdown, paste into LibreOffice and save as HTML, then push it up to git. It's not a beautiful solution but it works and should only take a minute. (You can even convert to mediawiki format, wink wink nudge..jk) @tomasz on the forums is having trouble accessing this git web interface so I will share his comments: https://dev1galaxy.org/post.php?tid=5147&qid=36878 "I've inspected the situation around this process and there are many things that I don't understand or think need fixing. I'll address only two now." 5. "First of all, it's not clear, why there are two repositories for documentation. Does the first one have any stand-alone purpose? Does it have to exist at all? With just one repository, there would be fewer integration problems. I'd just operate in the MD format (which can be simply plain text if clarity is preferred) and shift translation to HTML further in the build process. The HTML files are just artefacts. Of course there's a point in archiving them, but I wouldn't version them this way. A CI/CD line should take care of this. 6. "The documentation repository as it stands now would benefit from a clear licensing info. I see such notes in various files, but it's unclear in general, for the whole repo. Compare with the website repo, where this is explicit at the very top of the tree. The shell script linked in the migration instruction is simply unlicensed. A single SPDX line would do. But README.adoc also needs this info." So, in total there are 6 issues which I have numbered to make it easy to follow.
auanta closed this issue 6 months ago
auanta reopened this issue 6 months ago

@auanta . . . I am currently writing a history of how the website has morphed over the years which I will post when I have completed my trip down memory lane.

@auanta . . . I am currently writing a history of how the website has morphed over the years which I will post when I have completed my trip down memory lane.
You can read my response here: https://lists.dyne.org/lurker/message/20220809.184234.5ac660fc.en.html
Poster

Of course, historical context does help for future contributions in Chimaera www and docs. Thanks for that!

So, with help of the mailing list thread I can infer from @xenguy's recent commits (and the new thread) that the canonical documentation is represented on the live page, as intended. Maybe he's doing the documentation differently, that is, the documentation is being updated and managed only in the html webpage (www repo). Which does reduce any redundancy. What will happen to this repo, ./devuan/documentation? Seeing as it isn't being worked from, I suppose it will be archived?

If so, that explains point 1, 4, 5, and 6, especially if the old way of documentation is to be archived.

And the recent webpage changes now clarify number 2, as it shows the scripts are sort of user contributed, partial, not canonical but deemed good quality.

Is my understanding correct? Please let me know for sure...

Just don't forget about archiving this repo if workflow changes and Xenguy is not going to be updating it! :)

Anyways, with canonical docs confirmed, now we can get back to testing. As for any new issues with the migration, we can open new tickets.

But this opens new questions, where should we open the tickets if the problem is with a documentation step and not the website code? ./devuan/www? Or should we only go to the forum? I'll give you my perception. I think the forum should be for when a person needs assistance following docs, this assumes that the canonical documentation is correct. If it is found that there is an error with documentation or code, then a new issue should be opened on git. (If a legitimate issue is not opened on git, and only the forum or mailing list, it can fall through the cracks, especially in a team setting.) It's just a question of to which repo for documentation issues.

And that brings up why it's a good idea to keep the documentation repo in sync with www, because it allows for more than one guy to work on documentation (under the watch of a dev) without starting up a whole new wiki or falling back to some unofficial wiki. I feel that it would be too cluttered to have issues opened for documentation in www, but maybe that's not a problem since there isn't a lot.

Of course, historical context does help for future contributions in Chimaera www and docs. Thanks for that! So, with help of the mailing list thread I can infer from @xenguy's recent commits (and the [new thread](https://dev1galaxy.org/viewtopic.php?id=5158)) that the canonical documentation is represented on the live page, as intended. Maybe he's doing the documentation differently, that is, the documentation is being updated and managed only in the html webpage (www repo). Which does reduce any redundancy. What will happen to this repo, ./devuan/documentation? Seeing as it isn't being worked from, I suppose it will be archived? If so, that explains point 1, 4, 5, and 6, especially if the old way of documentation is to be archived. And the recent webpage changes now clarify number 2, as it shows the scripts are sort of user contributed, partial, not canonical but deemed good quality. Is my understanding correct? Please let me know for sure... **Just don't forget about archiving this repo if workflow changes and Xenguy is not going to be updating it! :)** Anyways, with canonical docs confirmed, now we can get back to testing. As for any new issues with the migration, we can open new tickets. But this opens new questions, where should we open the tickets if the problem is with a documentation step and not the website code? ./devuan/www? Or should we only go to the forum? I'll give you my perception. I think the forum should be for when a person needs assistance following docs, this assumes that the canonical documentation is correct. If it is found that there is an error with documentation or code, then a new issue should be opened on git. (If a legitimate issue is not opened on git, and only the forum or mailing list, it can fall through the cracks, especially in a team setting.) It's just a question of *to which repo* for documentation issues. And that brings up why it's a good idea to keep the documentation repo in sync with www, because it allows for more than one guy to work on documentation (under the watch of a dev) without starting up a whole new wiki or falling back to some unofficial wiki. I feel that it would be too cluttered to have issues opened for documentation in www, but maybe that's not a problem since there isn't a lot.

A lightbulb went off in my head earlier today when Xenguy and I were thrashing about the workflow issue.

The canonical way to prepare www for a new release would be to start a new branch in www titled something like "daedalus-beta". Current chimaera workspace is on the new-beta branch of www which gets published to the live site. None of the documentation for www has EVER been in "/documentation" except for dev1fanboys wiki which is an historical barnacle as explained in the post on d1g.

This was discussed extensively at our weekly meet yesterday. The /docmentation section is going through an extensive overhaul this weeked which should make things clearer.

In brief: "Keep art, maintainers, release-docs. Everything else can go into archive/history/trash."

This restructure will put current, up-to-date info at the top of the stack. I will be writing README.md to describe the historical significance of directories/files that will be moved down a level.

rrq keeps reminding me that documentation should really be in a wiki not /documentation but we can't seem to get it off the ground. My attitude is that "some place" is better than "no place" and the only place atm is www.

A lightbulb went off in my head earlier today when Xenguy and I were thrashing about the workflow issue. The canonical way to prepare www for a new release would be to start a new branch in www titled something like "daedalus-beta". Current chimaera workspace is on the new-beta branch of www which gets published to the live site. None of the documentation for www has EVER been in "/documentation" except for dev1fanboys wiki which is an historical barnacle as explained in the post on d1g. This was discussed extensively at our weekly meet yesterday. The /docmentation section is going through an extensive overhaul this weeked which should make things clearer. In brief: "Keep art, maintainers, release-docs. Everything else can go into archive/history/trash." This restructure will put current, up-to-date info at the top of the stack. I will be writing README.md to describe the historical significance of directories/files that will be moved down a level. rrq keeps reminding me that documentation should really be in a wiki not /documentation but we can't seem to get it off the ground. My attitude is that "some place" is better than "no place" and the only place atm is www.
golinux closed this issue 6 months ago
Sign in to join this conversation.
No Milestone
No Assignees
2 Participants
Notifications
Due Date

No due date set.

Dependencies

This issue currently doesn't have any dependencies.

Loading…
There is no content yet.