Contribute to the ITK Software Guide on GitHub

A major milestone in our transition to GitHub, migration of the contribution process for the ITKSoftwareGuide is now complete! :octopus: :heart_eyes_cat: :fireworks:

Documentation

An overview of the contribution process can be found in the README:

   $ git clone https://github.com/InsightSoftwareConsortium/ITKSoftwareGuide.git
   $ cd ITKSoftwareGuide
   $ ./Utilities/SetupForDevelopment.sh
   $ git checkout -b my-topic
   # make changes to local file(s)
   $ git add -- changedFileName
   $ git commit
   $ git review-push

More details can be found in CONTRIBUTING.md. Once ITK has transitioned, this will also be augmented by more detailed guidance in ITK’s CONTRIBUTING.md and the ITK Software Guide documentation, but this should be sufficient documentation if you already have basic familiarity with Git.

Git Hooks

The Git client side hooks have been updated for GitHub. Specifically,

  • The Gerrit Change-Id hook is disabled, if present.
  • The SetupForDevelopment.sh guides the contributor through setting up their GitHub account.
  • upstream and origin Git remotes are configured for development with GitHub forks.
  • git review-push and git pr aliases are configured to expedite the process of creating a pull request and checking it out locally, respectively.

CI Builds

We now have a CircleCI continuous integration build that will build your pull request and catch any build errors.

Once the build is complete, it is pushed to CDash. There is also a CDash status link available. Click on the Details link

It will bring us to the CDash build description.

Here, we can check the build for configuration errors or build warnings or errors.

Click the yellow package icon, and it provides links to the generated PDFs for inspection.

Docker Image

To avoid installation of the Software Guide’s build dependencies and its initial build time, a Docker image is available to quickly get started. More details on its use can be found in the README. This image is based on JupyterLab. It contains a browser interface to a console shell, text editor, and PDF previewer, so everything is available in the browser.

Instructions are also available in the README to set up a local, native build.

3 Likes

It indeed is.

Thanks @matt.mccormick for pushing this forward !

1 Like