Split documentation off into new repository, khmer-docs?

[ctb]

After 2.0 release, I'm thinking we should split the documentation off into its own repo and then try out the pull request hack:

http://felixge.de/2013/03/11/the-pull-request-hack.html

In that other repo, we could have branches that correspond to specific releases, with master corresponding to the latest master on khmer. So v2.0 would be the docs for khmer v2.0, but they could be updated routinely without going through a release.

Thoughts?

[mr-c]

I am a fan of the pull request hack.

This would make the use of submodules tempting to keep the docs next to the code. How about just split them prior to each release? That way the docs are still alongside the code during development.

Alternatively you could enable this on the main repo without splitting and use the new protected branches and required status checks to maintain sanity and have release be branches and not tags.

[ctb]

On Sat, Sep 05, 2015 at 01:37:20PM -0700, Michael R. Crusoe wrote:

I am a fan of the pull request hack.

This would make the use of submodules tempting to keep the docs next to the code. How about just split them prior to each release? That way the docs are still alongside the code during development.

-1 submodules; never heard anything good.

Keeping the docs up to date w/development is troublesome no matter how we do it; I don't see a clean solution either way (in separate tree, or in same tree).

Alternatively you could enable this on the main repo without splitting and use the new protected branches and required status checks to maintain sanity and have release be branches and not tags.

Sounds like management overhead, -0 from me.

[mr-c]

To recap:

To enable the community to update the docs easier using the Pull Request Hack we are considering:

1. Separate docs repo with one branch per release and one branch for master
2. Same as option 1 and the dev repo includes the docs via a submodule so that developers can update the docs as they make changes in the same PR
3. Separate docs repo only for released versions; development docs stay in the main dev repo and get copied over at release time.
4. Keep everything in the same repository and use the new GitHub required status checks to prevent roque commits to master.

My response:

1. "-1", the docs often get out of sync with the codebase, this would make it worse
2. "-1" I am also not a fan of submodules
3. "+1" slightly complicates the release but not by much
4. "+0" would require a more stable CI system. Otherwise "+2"

[betatim]

What is it we want to achieve with this?

On the idea of the PR hack: http://rfc.zeromq.org/spec:42/C4/ there is a lot of thinking in that document and I wonder if you need to adopt some of those ideas in addition to "give people commit rights".

From super small repos and bigger ones (like nteract/nteract) it seems that giving people commit access mostly leads to them not using it. IMHO you need an existing community (or ability to quickly grown one) that agrees on what "high quality" is and "enforces" that, otherwise it seems to spiral out of control (-> some people on the project will feel like they spend all their time tidying up after others).

[standage]

1. I agree that docs getting out of sync with code is a huge risk if we isolate docs in a dedicated repo.
2. I am not a fan of submodules.
3. Indifferent.
4. I agree that our current CI setup isn't robust enough to enforce status checks. But the protected branches go a long way in terms of disaster mitigation.

I'd be in favor of the PR hack, but would prefer that we kept the docs alongside the code.

[ctb]

With the move to Cython and oxli-ization (#1595) and people building on top of khmer (kevlar, and whatever @camillescott is doing) I'd like to revisit this. One compelling use case continues to be the ability to update docs independent of the need for a full khmer release.

[standage]

Yeah, after a few months I'm starting to see the appeal of this.

[ctb]

heh