JOSS review: Considering switching documentation to another branch . Something like gh-pages about floodlight HOT 2 CLOSED

@kanishkan91 thanks for the suggestion! We've considered your proposal thoroughly, and though we realize that outsourcing the documentation to a separate branch would allow leaner updates of the documentation, we still think that this benefit does not match the associated difficulties in our case. More precisely, we think that the following points can be problematic if the documentation was on a different branch:

• We use (a simplified version of) the git-flow branching model and have had positive experiences using it. Especially for less experienced users, this model gives clear instructions on how to merge new contributions and the different stages until changes reach the master branch. Adding a separate documentation branch would partially conflict with this model, as there is not a single develop branch to consider for new releases, but a parallel documentation branch to keep in mind as well.
• Although small changes to the documentation would be quicker with a separate branch, we'd argue this is exactly the opposite for larger changes: if a contributor wants to merge a larger feature/fix that also modifies the corresponding documentation to the package, he needs to create two independent pull requests - one for the code, one for the docs, which could be much harder to maintain and keep both PRs in sync if changes had to be made before acceptance.
• More generally and most importantly, splitting the documentation into a new branch will have it lose touch of the code-base. Since the docs are closely related to the code, it probably makes sense to keep them together. By splitting, code and docs could diverge from each other leaving outdated documenation, either because the code changed or the docs haven't been updated.
• As it stands, we directly use the package content to create the docs. For example, to keep the version number up to date automatically (see \docs\source\conf.py) or by using sphinx' autodoc to automatically generate module references from function docstrings. Thus, having the source on a different branch, all this functionality would break. There might be a workaround for this, but generally, this would require a refactor that is substantially larger than changing the branch for building the docs.
• We don't really see that updating the master branch (which is equivalent to a new release using the git-flow workflow) with "only" changes to documenation is an issue as you state. Especially since we follow Semantic Versioning, where changes in the documenation should also be represented by patch - this even explicitly requires a new merge into master. As we principally collect changes on the develop branch until a new release is scheduled (with a new merge into master), we also have the option to keep minor documentation changes on the develop branch until we feel it's time for a novel release, including documentation changes. If there's urgent documentation changes, a new patch is sensible anyways.

To sum up, we feel that separating the documentation on a new branch might be convenient, but could easily introduce more issues than it solves by risking that code and documentation could easily become out of sync (as discussed above). As we use readthedocs (in comparison to GitHub pages) for hosting, we also don't need a separate branch for serving.

Therefore, we'd prefer to keep the code-base and documentation together and cohesive, if that makes sense.

from floodlight.

@kanishkan91 @draabe this sounds reasonable to me. Thank you!

openjournals/joss-reviews#4588

from floodlight.