xcp_d Developer Guide

This guide provides a more detailed description of the organization and preferred coding style for xcp_d, for prospective code contributors.

Setting up your testing environment

xcp_d uses Docker to run tests locally. In order to run the tests locally, you must do the following:

1. Install Docker.

2. Create a testing directory. The tests will download and generate a lot of data, so it is a good idea to use a separate testing directory with symlinks of the testing files. For example:

   mkdir /path/to/testing/folder/
   

3. Symlink the xcp_d’s testing files to the new testing directory. For example:

   ln -s /path/to/xcp_d/.circleci/get_data.sh /path/to/testing/folder/get_data.sh
   ln -s /path/to/xcp_d/.circleci/CiftiWithFreeSurferTest.sh /path/to/testing/folder/CiftiWithFreeSurferTest.sh
   ln -s /path/to/xcp_d/.circleci/NiftiWithFreeSurferTest.sh /path/to/testing/folder/NiftiWithFreeSurferTest.sh
   ln -s /path/to/xcp_d/.circleci/NiftiWithoutFreeSurferTest.sh /path/to/testing/folder/NiftiWithoutFreeSurferTest.sh
   ln -s /path/to/xcp_d/.circleci/RunPyTests.sh /path/to/testing/folder/RunPyTests.sh
   ln -s /path/to/xcp_d/.circleci/tests /path/to/testing/folder
   

4. Create a local_xcpd_path.txt file within your new testing folder. This file should contain the path to your local clone of the xcp_d repository. For example:

   # Note that the path includes the xcp_d code subdirectory.
   # It's not just the path to the repository.
   echo "/path/to/xcp_d/xcp_d/" >> /path/to/testing/folder/local_xcpd_path.txt
   

5. Now, you can run the tests locally, within the new testing directory. The test scripts will call .circleci/get_data.sh to download the necessary data.

   # Then, to run any of the tests, you can run the test scripts in the new testing folder
   # Make sure that Docker is running beforehand!
   cd /path/to/testing/folder/
   bash CiftiWithFreeSurferTest.sh
   

Tip

If you want to re-run your tests, make sure that you delete the folders containing the files generated by your previous test runs. Otherwise, the xcp_d workflows will attempt to skip any pre-run steps.

Maintaining xcp_d

Making a Release

To make an xcp_d release, complete the following steps:

1. Choose a new version tag, according to the semantic versioning standard.

2. Modify the CITATION.cff file, updating the version number and release date.

3. In GitHub’s release tool, draft a new release.

   1. Create a new tag. Use semantic versioning terminology (e.g., 1.0.0). For pre-releases, use release candidate terminology (e.g., 0.0.12rc1).

   2. Define a release title. The release title should be the same as the new tag (e.g., 1.0.0).

   3. For pre-releases, select the “This is a pre-release” option.

   4. Select the “Generate release notes” button. This will create most of the necessary release notes based on xcp_d’s config file.

   5. At the top of the release notes, add some information summarizing the release.

4. Once the release notes have been completed, you can publish the release. This will make the release on GitHub.