How do I manage source code and accompanying documentation properly with git?

Question

I'm working on a software project which maintains the source code as well as the accompanying user manual (which includes tutorials and references and whatnot) in the same git repository. The user manual is written using DocBook.

The repository has different branches for different release branches. For instance, we have a 'major' branch to which features can be committed and out of which the next major release created. We also have a 'minor' branch to which only bugfixes may be committed, and out of which the next minor release is made. The minor branch is merged into the major branch quite often to make sure that all the bugfixes which have been done also end up in the next major release (so that we don't have a regression between e.g. v1.3 and v2).

The issue I'm seeing is that since the software between the major and minor branch is different (major contains new features), the documentation is different as well (the documentation in the major branch might have been rewritten in some places to mention the new features). Every now and then this causes conflicts in the DocBook sources when merging 'minor' into 'major' because single lines differ between the branches. This is actually true for other documentation files (like, ChangeLog files) true.

I recently started wondering how to improve this. My ideas included:

1. Just have one version of the manual for both the major branch and the minor branch. For version-specific features, explicitely say something like "Starting with v2 of the software, you can also do XYZ".
2. Move the documentation files into a dedicated git repository. This will still cause conflicts when merging the 'minor' branch of the repository into 'major', but at least all the software developers who work on the source code don't see (and get annoyed by) the conflicts.
3. Use dedicated git repositories and embed them as git submodules into the original repository. I'm not quite sure what this would gain me, but I heard it's a bit painful to use submodules like this because I'd end up updating the reference commit to be pulled from the foreign repository all the time.

I'm wondering - how does everybody else handle this situation of keeping source code and documentation together? Note that I'm not talking about API documentation (which can be generated from source code automatically) here but plain, manually written, english text.

Answer 1

I believe the "option 3" (submodules) would still be the least annoying, since it:

• decouples the two set of files (you don't need the latest version of documentations to compile and run your project)
• most git commands are now "submodules-aware" (or, on the contrary, can ignore them like git status)
• you can update a submodule whenever you want (it doesn't have to be "all the time")
• you will keep a link between source codes and documentations through the parent repo.

That being said, I don't see an easy solution for managing parallel evolutions in a text files. Conflicts will still be there.