GNIP 72 - Move docs in a separate repository

[t-book]

📙 GNIP 72 - Move docs in a separate repository

Overview

My proposal is to move the documentation out of our GeoNode base repository.

Advantages:

• Travis will not be blocked by useless tests when docs are updated
• Git clone of GeoNode Core will work faster due to reduces file size ~260 mb!
• Issues can be treated differently. F.e. We could consider merging small fixes without issue.

Proposed By

t-book | [email protected]

Assigned to Release

This proposal is for GeoNode 2.8 – master.

State

• Under Discussion
• In Progress
• Completed
• Rejected
• Deferred

Implementation

1. create repository geonode/documentation
2. push docs directory of branches 2.8 – master
3. delete docs directory in core
4. update RTD to point to our new docs repository

We need to be careful with branches and double-check the active versions at RTD afterward.

Backwards Compatibility

I cannot think of any problems as cool URIs do not change.
https://www.w3.org/Provider/Style/URI

Voting

Project Steering Committee:

• Alessio Fabiani
• Francesco Bartoli
• Paolo Corti
• Simone Dalmasso
• Toni Schönbuchner:

[afabiani]

@t-book repo available here https://github.com/GeoNode/documentation

[t-book]

@afabiani nice thank you!

[t-book]

@afabiani @gannebamm

I've created a test repository
https://github.com/t-book/testdocs

• moved docs folder to the root
• pushed all tags / and branches to not lose anything

git clone https://github.com/geonode/geonode; cd geonode
git branch -a | grep -v HEAD | perl -ne 'chomp($_); s|^\*?\s*||; if (m|(.+)/(.+)| && not $d{$2}) {print qq(git branch --track $2 $1/$2\n)} else {$d{$_}=1}' | csh -xfs
git fetch --all; git pull 
git filter-branch --prune-empty --subdirectory-filter docs -- --all
git remote add newdocs https://github.com/t-book/testdocs.git
git push newdocs --all
git push newdocs --tag

which results in
https://new-testdocs.readthedocs.io/en/master/

---

I would repeat this with GeoNode organization as soon as other PSC members have made their vote.

---

One question:
IMHO opinion, the current naming of branches at RTD (master, latest, stable, …) is not really clear for users? How about getting rid of latest and just having something like:

master    -> github master branch # might still not be 100% clear for users but good for devs?
stable    -> always current stable (2.10.1 currently, soon 2.10.2 tag)
2.8.1     -> Former stable, ancient versions

If you have other suggestions for a clear naming or just like to keep it like it is I’m all ears

[afabiani]

@t-book +1 getting rid of latest one. I would probably prefer having docs related to the versions, like 3.0 and 2.10.1, 2.10.2 ... however, your nomenclature could work either.

[t-book]

@afabiani I fully agree having only versions for releases would be the optimum. However, I think we still need a master branch (or version) for ongoing work on docs. As soon a new release arrive we tag the master branch and publish the docs for it.

[afabiani]

@t-book ok to keep master, however, usually, master branch has a version too which should be incremented when a new release has published.
Anyway, I have no strict requirements or preferences on this.

[gannebamm]

I am in favor of alessios idea:
Get rid of stable and latest,
Have version tagged docs (2.10.1,...),
Have master as current dev state. Which is clear for dev since master aligns with master branch on geonode repo

[t-book]

Thanks to both of you. This is how it will/could look like: https://new-testdocs.readthedocs.io/en/master/
Nice and tidy only master and releases.

[frafra]

Sorry to interrupt you :-) I just have a quick question on branches and releases: should minor releases have specific documentation? Like 2.10.0 vs 2.10.1?
Features should stay the same, setup almost identical I suppose, but I do not expect someone to try to install a older minor release.

[t-book]

@frafra good point!

Master -> Master
2.10   -> 2.10 stable release branch or tag 
2.8    -> 2.8  stable release branch or tag

?

[frafra]

@t-book that would be my idea if there is no special need to have branches for minor releases too.

[t-book]

@frafra I would go with your suggestion. the simpler the better. We can still publish minor versions in case it's needed or @afabiani or @gannebamm request it.

thanks for your feedback!

[gannebamm]

@frafra is right. I don't think we need minors for docs.

Our approach should be optimizing for manageable chunks of documentation. Currently it's to much of it

[capooti]

+1 thanks Toni!

[t-book]

1. Repository filled

• master
• 2.10 (former tag 2.10.2)
• 2.8 (former tag 2.8.1)

have been created at https://github.com/GeoNode/documentation

2. test build

A test build can be seen here https://geonode-documentation.readthedocs.io/en/latest/
As @frafra suggested we do not have minor versions anymore. RDT reflect what it finds at github (master, 2.10, 2.8)

3. To do

• point RTD (CNAME docs.geonode.org) to new github repository (I would wait for missing +1s)
• delete docs repository in geonode main repository
• delete requirements_docs.txt

[francbartoli]

+1 @t-book and thanks for proposing it

[t-book]

• DNS is changed
• Old docs are still up as backup (https://geonode.readthedocs.io/en/2.10.x/ delete them after one week?)
• Webhook for RTD has been removed from master
• Webhook has been added to new documentation repository

[afabiani]

@t-book please remember to update the wiki page also, thanks!

[t-book]

@afabiani done (edited GNIP page) thanks for reminding!