documentation for multiple releases at Jamulus.io

[gene96817]

I tried to put this in jamuluswebsite but this is neither a bug nor a translation issue.

As preparation proceeds for 3.8.1, it would be really helpful to have the website preserve documentation for earlier release. Two reasons:
1- Some users choose to delay upgrading, especially the less tech-savvy users. It is sometimes necessary to go back to the documentation for their release to solve problems.

2- When I install a new release, it is helpful to be able to roll back to the old release. Just saving a snapshot of the past installation is not sufficient. There may have been changes to the system too. Or it may be helpful to compare features between the old release and the new release to help with troubleshooting why the new release install is failing. (Sorry my memory is not good enough to remember all the documentation for the old release.)

It would be great if the documentation for the past "few" releases were available. If it is too late to do that, it would be helpful to start this practice of keeping easy access to documentation to previous releases.

[ann0see]

Hmm. I think it theory it is possible to have access to the old information since we're using git. If it's easy to implement we can probably develop something.

Maybe the web archive is a first step: https://web.archive.org/web/20210201010808/https://jamulus.io/

This was tagged around the time of the last release: https://github.com/jamulussoftware/jamuluswebsite/tree/r_website_3_8_0 (but ofc. that's not user friendly at all.)

Edit: I'm afraid I can't develop much in this direction but maybe we find someone else?

[gene96817]

Oh, I forgot that a few month, after more than a week of trying, I never succeeded in building the documentation from github. (It was so painful I forgot. LOL)

I wish I can help but since I cannot build the documentation on my MacBook there is nothing I can do.

Here is a deal. If someone will help me get succeed in building the documentation, I will spend at least a week looking at the documentation.

[gene96817]

Looking at the long explanation from an hour ago, is this a problem related to relative vs absolute addressing.
One example was https://github.com/jamulussoftware/jamuluswebsite/blob/release/assets/css/fw.css.
Does this mean that we need to plan ahead so that the releases should be in
https://github.com/jamulussoftware/jamuluswebsite/blob/release/assets/css/3.8.0/fw.css
and then in https://github.com/jamulussoftware/jamuluswebsite/blob/release/assets/css/3.8.1/fw.css.
In that way the source files are all in a "release-N" tree and then the next release is in a "release-N+1" tree.

I am not asking this to be retroactive but it could be really worthwile to start doing this going forward from the current 3.8.0 set of files.

[ann0see]

Yes, but I think this is much more complicated than the git approach ;-).

The git approach is basically a copy of the site (+ all the hosting and build logic on GitHub). You'd only need to remember a few commands to update the page. GitHub even builds the site for you and publishes it on the web.

Thanks to @ignotus666, you could work locally by using the .zip files which each PR produces and test the site without a full build environment on your mac. But I assume the git approach is simpler and more accessible.

If you have time, you might want to try the local approach, but I'd strongly suggest not (at least for now): https://gist.github.com/ann0see/f738f79fe907487544eb128acf504d4d

What about I create the GitHub account and give you hints on how to handle it?

[jamulusold]

Voilà: https://jamulusold.github.io/ (that's a fork of jamulussoftware/jamuluswebsite but with GH pages enabled and the robots.txt file modified so that google doesn't index it)

[jamulusold]

Currently this website is up to date, but as soon as the next release comes up, you'd simply not update it. Once the next release comes up, you'd click on "fetch upstream" to "freeze" the site

(note: you could handle the website via cli and might need to if there are conflicts. However, the I'm sure there are many people in the community who can help you to solve the conflicts).

[ann0see]

By the way: if you want to contribute to the documentation, feel free to edit the specific files here: https://github.com/jamulussoftware/jamuluswebsite/tree/next-release/wiki

[gene96817]

Thanks for the invite. I'll find some time to wade through some of the files.

[ghost]

I think jamulus 3.6.2 is a good point for older documentation, it took into consideration slower development to this point and Debian releases.

[ann0see]

Who wants the login data to @jamulusold ? I'd share them privatly with someone (encrypted E-Mail/messenger/whatever) @gene96817 @DavidSavinkoff ?

Still happy to onboard someone to this approach, but I don't want to maintain it.

[jamulusold]

The only thing you need to keep in mind is that the robots.txt file should disallow indexing of the page to ensure jamulus.io still doesn't suffer from duplicate content/SEO issues.

[gene96817]

I am glad to see this discussion. I apologize for being a dunce. What do I need to know to be able to review (a) the emerging documentation for 3.8.1 and (b) read the mentioned past documentation? I am good at following instructions. As some of you know, as soon as I get an error in the process, I easily get stuck.

I installed git on my MacBook with "brew install git". It completed without any error messages. Then from @jamulusold above I ran "git remote add upstream [email protected]:jamulussoftware/jamulus". The results was "fatal: not a git repository (or any of the parent directories): .git". So now I am stuck. It worked for @jamulusold, what did I do wrong?

[ann0see]

@jamulusold is me ;-).

What you need to do:

1. git clone [email protected]:jamulusold/jamulusold.github.io
2. cd jamulusold.github.io
3. the mentioned commands from above. In order to execute git push --force origin HEAD:gh-pages I need to give you write access to the repo (and probably the password too). Will do that

[jamulusold]

You should have received an invite now and the instructions should be up to date (hopefully)

The site is available at https://jamulusold.github.io

[jamulusold]

What do I need to know to be able to review (a) the emerging documentation for 3.8.1

That's not possible at the moment, but clearly worth a discussion. Could you please open an issue on jamuluswebsite and ping gilgongo and ann0see?

[jamulusold]

Actually it's much easier than I thought if we only use the gh-pages branch: https://github.com/jamulussoftware/jamuluswebsite/commits/gh-pages

Once you know the commit (=state of site) on the gh-pages branch of jamulussoftware/jamuluswebsite which you want to publish, it's easy:

First of all - if you haven't already, clone the repo (=copy to disk). You only need to do this once:

git clone [email protected]:jamulusold/jamulusold.github.io

Now go into the folder with all the files:

cd jamulusold.github.io

Now add the jamulussoftware/jamuluswebsite repository as "upstream" repository to ensure getting the latest data which is published on jamulus.io:

git remote add upstream [email protected]:jamulussoftware/jamuluswebsite

---

The following needs to be done on every update:
git fetch upstream - to update your local copy to get the latest commits from jamulussoftware/jamuluswebsite
git checkout <commit ID> - to get the state you want to publish (you got the commit ID from the link I mentioned above)
git push --force origin HEAD:gh-pages - to upload the site to https://jamulusold.github.io

Afterwards run the following commands to ensure Google doesn't index it:

git checkout origin/gh-pages && git pull

Now edit robots.txt (e.g. with nano robots.txt)
...and ensure that it has the following content (this tells Google not to index the page):

User-agent: *
Disallow: /

Exit nano with CTRL-X, now confirm writing to disk with y which will exit nano.
Now add robots.txt to the repo with the following commands:
git add robots.txt
git commit -m "Disallow indexing from Google"
git push - to upload the last change to the website.

Voilà, the site should be available here: https://jamulusold.github.io