Hi all, We have a bit of a confusing situation currently with the docs. Hopefully this mail will help clarify it.
12 days ago, two pull requests were opened which proposed to move a bunch of documentation from the main (i.e. top-level) crowbar repository into the barclamp-crowbar repository: https://github.com/crowbar/crowbar/pull/1959 https://github.com/crowbar/barclamp-crowbar/pull/792 These couldn't be submitted as a pull request bundle, because (last time I checked, at least) the ./dev tool doesn't support bundles which affect the main repo. Unfortunately this resulted in #792 getting merged but #1959 getting closed after discussion in which Victor and I raised strong objections. As most people know, the main repo doesn't (yet) have any active branching strategy, and currently represents files which are shared across all releases (with the exception of the releases/ subtree). In contrast, barclamp-* have a branch per release. Therefore the net effect of the above is as follows: - All Crowbar releases still have a lot of documentation in the main repo. - For 2.0, all this documentation is also duplicated in the master branch of barclamp-crowbar, in a different layout (some of the files previously under doc/ are now under doc/misc_docs). Therefore the 2.0 docs have effectively been forked, and AIUI this means: - If you are working on 2.0, you should *only* edit the docs in barclamp-crowbar's master branch, and ignore the docs in the main repo. - If you edit the copy in the main repo, the change will effectively apply to *all* releases except 2.0. Did I get that right? In the last 12 days, both sets of docs have been changed in non-identical ways. I didn't check to see whether those changes adhere to these proposed guidelines. This is unfortunately a very confusing situation to be in, especially considering that we already have documentation debt from other duplications in the past which were never cleaned up (some involving the wiki). As per: https://github.com/crowbar/crowbar/pull/1959#issuecomment-29846696 Mike said he will sort out the release specific stuff as he re-organizes the 2.0 branch of the docs. This will improve things in the short-term. Once again may I reiterate how much the lack of branches in the main repo is hurting us. I'm looking forward to seeing some progress on this thread when Victor has time to reply ;-) http://lists.us.dell.com/pipermail/crowbar/2013-December/004174.html _______________________________________________ Crowbar mailing list [email protected] https://lists.us.dell.com/mailman/listinfo/crowbar For more information: http://crowbar.github.com/
