This guide provides a more detailed description of the organization and preferred coding style for xcp_d, for prospective code contributors.
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.
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.
- Create a new tag. Use semantic versioning terminology (e.g.,
- Once the release notes have been completed, you can publish the release. This will make the release on GitHub.