Uploaded image for project: 'CiviCRM'
  1. CiviCRM
  2. CRM-15867

Reconcile gitify/buildkit docs

    Details

    • 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:

      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.)

        Attachments

        1. devhome.bmml
          11 kB
          Tim Otten
        2. devhome.png
          327 kB
          Tim Otten

          Activity

            People

            • Assignee:
              timotten Tim Otten
              Reporter:
              timotten Tim Otten
            • Votes:
              0 Vote for this issue
              Watchers:
              4 Start watching this issue

              Dates

              • Created:
                Updated:
                Resolved: