#2709 Issue `closed`: Wiki about workflows and dir structure¶

Labels: support / question, no-issue-activity

DEvil0000 opened issue at 2021-11-11 21:55:¶

Is there documentation I missed on the following topics?
If it is missing a short description in wiki or readme files would provide some help and guidence to stick with the structure.

what directroy holds what e.g. lib/output/pack/format
sub directory structure e.g. default/...
what workflows call to what directories and in which order

Thanks

jsmeix commented at 2021-11-12 09:18:¶

Off the top of my head I only know about
https://github.com/rear/rear/blob/master/doc/user-guide/09-design-concepts.adoc
and
usr/share/rear/restore/readme
usr/share/rear/restore/OPALPBA/readme
usr/share/rear/wrapup/readme
usr/share/rear/finalize/readme
usr/share/rear/backup/readme
usr/share/rear/prep/README
but all that is possibly incomplete and partially outdated, cf.
https://github.com/rear/rear/blame/master/doc/user-guide/09-design-concepts.adoc

Regarding what workflows call:
You could run each workflow in simulation mode like

# usr/sbin/rear -s recover

to see what scripts in which so called 'stage' directories are actually sourced
or you inspect the usr/share/rear/lib/*workflow.sh sources.

Regarding 'stage' directories:
See the SourceStage function in lib/framework-functions.sh
https://github.com/rear/rear/blob/master/usr/share/rear/lib/framework-functions.sh

DEvil0000 commented at 2021-11-12 10:23:¶

https://github.com/rear/rear/blob/master/doc/user-guide/09-design-concepts.adoc

this is mostly what i was looking for. I was somehoe not expecting it to be in user guide.
Also it is very brief in some cases and does not explain other workflows like format.

I think one issue with finding information is where too look for. there is docs directroy, readme files at some places, wiki and website. All places provide a different but not defined set of incomplete information.

You could run each workflow in simulation mode

yes, I figured that out at some point. thats helpfull but there should be no need to look at that in the first place I think. How about a print for every new time a new directory gets sourced e.g. Starting pack phase

jsmeix commented at 2021-11-12 10:30:¶

In current master code there is a print when a new stage directory gets sourced
which is shown in debug modes to not clutter the user's terminal in normal modes, see
https://github.com/rear/rear/blob/master/usr/share/rear/lib/framework-functions.sh#L99
cf. https://github.com/rear/rear/commit/ae9c64597d3b73112e8845e96ad1cb2ca40fac25

gdha commented at 2021-11-14 11:04:¶

@jsmeix Wouldn't it be better to move the ReaR documentation to one place - https://github.com/rear/rear-user-guide (site: https://relax-and-recover.org/rear-user-guide/index.html)? The documentation is currently spread over internal documents without a real good overview towards the end-user. One find examples in the config tree, examples in the docs, examples in the mailing list. It would be better to merge the best examples at one place. However, alone it is too much work for me. I need help from the community.

jsmeix commented at 2021-11-15 09:25:¶

@gdha
same for me regarding available time:
As long as I have real issues to solve in the code
I won't have time to improve the documentation (outside of the code).
What I would do - as time permits - is fixing specific bugs in existing documentation
(but neither reorganizing the documentation nor adding new bigger documentation)
provided someone tells me where a bug is in the documentation.
I don't have time for proofreading all existing documentation.

DEvil0000 commented at 2021-11-18 13:22:¶

If there is a clear gideline what kind of documentation is wanted and where to put it someone may do a PR or edit documentation at some point. There should be a plan and some guidance in any case.

gdha commented at 2021-11-19 08:53:¶

@DEvil0000 You could create an issue at https://github.com/rear/rear-user-guide/issues to express your ideas/wishes.
We will try to create a frame-work and migrate the current documentation to its new place.

@rear/wiki-contributors @rear/contributors
If every ReaR contributor or expert user contributes a little bit then the documentation will grow gradually to a nice collection of documents. If I have to do it alone (what the current situation is) then it will take many years to complete, if it ever completes.

DEvil0000 commented at 2021-11-19 17:58:¶

Does "user-guide" only include user facing documentation? where do you want to put dev facing information about inner workings or coding guidelines? So - what kind of information is where? Or should both go into one place?
Why not keep it in this repo?

What is the preferred format? markdown?

Should it be rendered as web help in some way (in the future)? how about hugo (so markdown is still the input source)? Also what should go on the website and should the current one change (documentation wise)?

Do you want me to open issues there for those points? At least the first point would make sense to clarify first right?

gdha commented at 2021-11-20 09:34:¶

The ReaR User Guides uses mkDocs and is written in MarkDown already. The rendering to web-pages is done automatically after each PR via GitHub Actions.
My first thought was to make the User Guide as complete as possible including a developers section (why not?). On longer term I would remove the documenation from the ReaR main sources and keep it at one place as it doesn't make sense to duplicate the documentation.
Personnally I use a docker image to write on the documentation as such it is a bit more portable ;-) (at least for me). And, it is easier to test updates on the underlying software.

Sure open issues so we can have a dicsussion on each point seperate. The more people involved the better I would say.

github-actions commented at 2022-01-20 02:25:¶

Stale issue message

[Export of Github issue for rear/rear.]

#2709 Issue closed: Wiki about workflows and dir structure¶