Hello Docs team, I was wondering if any decision has been made...? Personally I'm for option A.
Thanks, Carlos From: opnfv-tech-discuss-boun...@lists.opnfv.org [mailto:opnfv-tech-discuss-boun...@lists.opnfv.org] On Behalf Of Kunzmann, Gerald Sent: 19 January 2017 09:33 To: opnfv-tech-discuss@lists.opnfv.org Subject: [opnfv-tech-discuss] [opnfv-docs] References in documentation to master or release files? Dear OPNFVDOCS Team, We are discussing about the pros/cons of referencing in documentation to master or release files. A) The correct (?) way: always refer to master files/URLs in master branch and refer to release files/URLs in release branches. For example, someone trying to git clone origin/stable/danube as documented in master branch will fail. Instead, pointing to a specific release should only happen in the corresponding release branch. Also, rendered files in artifacts.opnfv.org from master branch (e.g. http://artifacts.opnfv.org/doctor/docs/manuals/mark-host-down_manual.html) should be placed under a 'master' directory just like it happens to rendered files from release branches. Consequences: When updating the documentation prior to branch split, we would have to use references to master and at branch split update all references to release branch. And patches that are being cherry picked to the release would require changing the links contained in it. Also, the references would have to be updated for each release. B) The pragmatic way: reduce the need/effort to update such links from release to release and use references to master for those parts of the documentation that will not change for the release, e.g. references to some manuals where we don't have any plans to update those parts of the code. See also the discussion and example in https://gerrit.opnfv.org/gerrit/#/c/24365/ We are not sure what would be the preferred/recommended way. Some recommendations by the opnfvdocs team would help the different projects to use a common approach. I would like to get some more feedback from other OPNFV'ers on how to best address this. Best regards, Gerald =============================================== Dr. Gerald Kunzmann, Manager DOCOMO Communications Laboratories Europe GmbH Landsberger Strasse 312, 80687 Munich Tel: +49-89-56824-239 / Fax: +49-89-56824-300 Web: http://www.docomoeurolabs.de<http://www.docomoeurolabs.de/> Geschäftsführer: Atsushi Takeshita, Dr. Thomas Walter, Hisahiro Hamahata, Hiroyuki Oto, Kei Tonokura, Amtsgericht München, HRB 132976
_______________________________________________ opnfv-tech-discuss mailing list opnfv-tech-discuss@lists.opnfv.org https://lists.opnfv.org/mailman/listinfo/opnfv-tech-discuss
