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:
Install Docker.
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/
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
Create a
local_xcpd_path.txt
file within your new testing folder. This file should contain the path to your local clone of thexcp_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
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:
Choose a new version tag, according to the semantic versioning standard.
Modify the CITATION.cff file, updating the version number and release date.
In GitHub’s release tool, draft a new release.
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
).Define a release title. The release title should be the same as the new tag (e.g.,
1.0.0
).For pre-releases, select the “This is a pre-release” option.
Select the “Generate release notes” button. This will create most of the necessary release notes based on
xcp_d
’s config file.At the top of the release notes, add some information summarizing the release.
Once the release notes have been completed, you can publish the release. This will make the release on GitHub.