stricter process in the manual

[xmonader]

As we have multiple networks, the docs need to always reflect the real status of the software

so for the branches

• development always has the latest of devnet and should be hosted on www2.manual.grid.tf
• main reflects the latest on mainnet, and should be hosted on manual.grid.tf

the changes and reorganization: please make sure to do that carefully, multiple people already sent complaints about outdated links or 404 pages

[Mik-TF]

Good. Here is a proposition to make the most out of this new direction:

Proposition

I propose the following to be done sequentially.

Steps

• Merge all current PRs and check that no 404 are left
  • as we have major changes in organization of the manual(see www3 version)
• protect master branch (to enable two branch flows, master and dev, see below)
• demand to codeowners that from now on each branch have clear prefixes
  • master_ for main and test net content
  • dev_ for dev net content
• put dev branch mdbook to www.manual.dev.grid.tf instead of www2.manual.grid.tf (will be easier for people to understand, as we do the same with dashboard, etc.)
• add www2.manual.dev.grid.tf as dev net content staging version (more on this below)
• adjust workflows accordingly with website link checker

Outcome

• info_grid organization
  • main/test net
  • www.manual.grid.tf for production version of main/test net content
  • www2.manual.grid.tf for staging version of main/test net content
  • dev net
  • www.manual.dev.grid.tf for production version of dev net content
  • www2.manual.dev.grid.tf for staging version of dev net content
• benefits of prod and staging version for main/test and dev content
  • the staging version will always trigger the website link checker, so we know if 404 errors are there.
  • if there are 404 errors, we fix them and repush to staging versions.
  • when no more 404 errors, we can push to production version and know there are no 404 errors.
• users pov
  • users will use manual.grid.tf for main and test net
  • users will use manual.dev.grid.tf for dev net
• differences between main/test and dev manual
  • we write clearly in the book.toml
  • title = "TFGrid Manual (mainnet/testnet)"
  • title = "TFGrid Manual (devnet)"
    • so it's at the top of each page, as clear as can be.

@xmonader @ramezsaeed What do you think?

[Mik-TF]

@scottyeager Feel free to chime in here. As we are discussing to protect the master branch as well as some other major updates to the manual.

[Mik-TF]

@xmonader does my proposition make sense? We could go forward with this. But it depends if Kristof moves the whole manual to gitea as discussed in the TG group.

[Mik-TF]

@xmonader nvm the above around gitea.

Focusing on info_grid, we can implement the process developed at the beginning of the issue.

I think this, along with #438, will provide a great improvement to the manual and it will be easier to read the manual, on the users side, and to write the manual, on the devs side.

[Mik-TF]

Once PR #444 is merged, I will work on the new workflow as stated above.

Something to note: since we are at the beginning of a new cycle, dev=test=main (once we have 3.13 as the new main dashboard). Thus the dev and the main+test manual websites will be the same. Then we will make changes in dev as we get new features there, and when we arrive at the end of another cycle, where we merge the changes from dev net to main+test net, we can merge the dev manual into the test+main manual.

[Mik-TF]

WIP: https://github.com/threefoldtech/info_grid/tree/development_process/.github/workflows

@ramezsaeed if you want to have a look. It's not done, but the work has started.

Things to note:

• Branches would be
  • master, master_staging, development, development_staging
• We'd need to add the following directories on the server hosting the manual (see workflow for info on this):
  • websites/master/info_grid/
  • websites/master/staging/info_grid/
  • websites/development/info_grid/
  • websites/development/staging/info_grid/
• We'd also need to create the branches and then set the git repo on each directory shown above

[Mik-TF]

Note: In practice this issue could be closed: we make sure main manual only has main/test nets info. And we make sure broken URLs are fixed. So all's fixed in that sense.

If we want to go further:

We can simply rename www2.manual.grid.tf to www.manual.dev.grid.tf and make sure we push to main branch only what is ready for main and test nets. E.g. currently we wait until dedicated machine changes on dashboard are brought to main and test before merging the manual dev branch (www2) to www.

What do you think @xmonader?

In this case we need to:

• adjust DNS records for www2.manual.grid.tf -> www.manual.dev.grid.tf
• adjust workflow with dev.grid.tf

[Mik-TF]

WIP

Almost done.

@xmonader can you please have a look at this PR that was merged: https://github.com/threefoldtech/info_grid/pull/529#event-12800182912

Todo

• The workflow has been updated
• I think now we need to set the server hosting the manual to be able to host the dev branch on www.manual.dev.grid.tf

Let me know if I can help but I don't have access to this server so someone else should be able to work it out. Thanks!

Rerences

Here's the new workflow:

[Mik-TF]

Work is done, now we need to update the server, see this issue

Maybe @ramezsaeed has access to the server? Thanks!

[xmonader]

Hi Mik thanks for the hard work on here, I wasn't able to catch up.

Only operations have access to company services so you can ask @sabrinasadik to help operationally.

[Mik-TF]

we now have

• main and test: manual.grid.tf
• dev: manual.dev.grid.tf