Details
-
Type: Improvement
-
Status: Done/Fixed
-
Priority: Minor
-
Resolution: Fixed/Completed
-
Affects Version/s: 4.6
-
Fix Version/s: Unscheduled
-
Component/s: None
-
Labels:
-
Versioning Impact:Patch (backwards-compatible bug fixes)
-
Documentation Required?:Developer Doc
-
Funding Source:Needs Funding
Description
There are two main workflows for setting up a developer environment in git:
- Use an existing site-build based on a tarball; run "gitify".
- Create a new site-build that replicates the test/demo systems; run "civibuild".
The docs for these are split among:
- http://wiki.civicrm.org/confluence/display/CRMDOC/GitHub+for+CiviCRM
- https://github.com/civicrm/civicrm-buildkit/blob/master/README.md
- https://buildkit.civicrm.org
- https://civicrm.org/participate/developer
- http://wiki.civicrm.org/confluence/display/CRMDOC/Develop
- http://wiki.civicrm.org/confluence/display/CRMDOC/Overview
- http://wiki.civicrm.org/confluence/display/CRMDOC/Basic+set+up
There are a few problems with the current presentation:
- "GitHub for CiviCRM" uses "gitify" without buildkit; consequently, several useful tools ("hub", "git scan", "civilint", etc) are not downloaded.
- "GitHub for CiviCRM" omits any directions/links on running unit-tests, checking style, or coordinating updates across multiple git repos – which should be basic tasks for anyone writing a patch.
- The git remotes are setup differently by "gitify" and "hub". The meaning of "origin" is conflicted. Consequently, many "git" commands aren't directly interchangeable, so some docs are duplicated.
- gitify: "origin"==my fork, "upstream"==canonical repo
- hub: "origin"==canonical repo, "myname"==my fork
- The use-cases for the three docs are overlapping but not equivalent.
- Gitify sets up git-hooks (e.g. for JIRA footnotes and php -l) but buildkit doesn't.
Proposal: Remix the content. Substantive changes:
- Download buildkit regardless of whether one uses gitify or civibuild.
- Recommend "hub". Consistently use its naming conventions in all docs/scripts.
- When there are two variations on a step (e.g. "run gitify" vs "run civibuild"; "run hub" vs "goto github.com"), use tabs or accordions - or link to separate pages.
Open question: The docs have three mediums, and I'm deeply torn between between them:
- Git+Markdown (README.md): Simple feature-set. Read+edit locally or online. Mixing text+code is really easy. This is really common for FOSS projects on github. No tabs/accordions. Need Github account to contribute.
- Confluence (wiki.civicrm.org): Feature-set is a bit more powerful/complex. Don't need HTML/git skills. Read+edit online – but not offline. No tabs/accordions. Need Confluence account to contribute.
- Angular (https://github.com/totten/ciui): Precise control, slicker look. Add intelligence/filtering/tabs/accordions. Requires JS/HTML skills to edit. Read online; read+edit offline (but that requires setting up node/grunt). Need Github account to contribute.
(Note: Given that the audience is being directed to setup forks on github and work on PHP code, it doesn't feel onerous to require github/Markdown/HTML skills.)