diff --git a/.github/CONTRIBUTING.md b/.github/CONTRIBUTING.md
new file mode 100644
index 0000000..6f7efed
--- /dev/null
+++ b/.github/CONTRIBUTING.md
@@ -0,0 +1,262 @@
+# Contributing to XAVIER
+
+## Proposing changes with issues
+
+If you want to make a change, it's a good idea to first
+[open an issue](https://code-review.tidyverse.org/issues/)
+and make sure someone from the team agrees that it’s needed.
+
+If you've decided to work on an issue,
+[assign yourself to the issue](https://docs.github.com/en/issues/tracking-your-work-with-issues/assigning-issues-and-pull-requests-to-other-github-users#assigning-an-individual-issue-or-pull-request)
+so others will know you're working on it.
+
+## Pull request process
+
+We use [GitHub Flow](https://docs.github.com/en/get-started/using-github/github-flow)
+as our collaboration process.
+Follow the steps below for detailed instructions on contributing changes to
+XAVIER.
+
+
+
+### Clone the repo
+
+If you are a member of [CCBR](https://github.com/CCBR),
+you can clone this repository to your computer or development environment.
+Otherwise, you will first need to
+[fork](https://docs.github.com/en/pull-requests/collaborating-with-pull-requests/working-with-forks/fork-a-repo)
+the repo and clone your fork. You only need to do this step once.
+
+```sh
+git clone https://github.com/CCBR/XAVIER
+```
+
+> Cloning into 'XAVIER'...
+> remote: Enumerating objects: 1136, done.
+> remote: Counting objects: 100% (463/463), done.
+> remote: Compressing objects: 100% (357/357), done.
+> remote: Total 1136 (delta 149), reused 332 (delta 103), pack-reused 673
+> Receiving objects: 100% (1136/1136), 11.01 MiB | 9.76 MiB/s, done.
+> Resolving deltas: 100% (530/530), done.
+
+```sh
+cd XAVIER
+```
+
+### If this is your first time cloning the repo, you may need to install dependencies
+
+- Install snakemake and singularity or docker if needed (biowulf already has these available as modules).
+
+- Install the python dependencies with pip
+
+ ```sh
+ pip install .
+ ```
+
+ If you're developing on biowulf, you can use our shared conda environment which already has these dependencies installed
+
+ ```sh
+ . "/data/CCBR_Pipeliner/db/PipeDB/Conda/etc/profile.d/conda.sh"
+ conda activate py311
+ ```
+
+- Install [`pre-commit`](https://pre-commit.com/#install) if you don't already
+ have it. Then from the repo's root directory, run
+
+ ```sh
+ pre-commit install
+ ```
+
+ This will install the repo's pre-commit hooks.
+ You'll only need to do this step the first time you clone the repo.
+
+### Create a branch
+
+Create a Git branch for your pull request (PR). Give the branch a descriptive
+name for the changes you will make, such as `iss-10` if it is for a specific
+issue.
+
+```sh
+# create a new branch and switch to it
+git branch iss-10
+git switch iss-10
+```
+
+> Switched to a new branch 'iss-10'
+
+### Make your changes
+
+Edit the code, write and run tests, and update the documentation as needed.
+
+#### test
+
+Changes to the **python package** code will also need unit tests to demonstrate
+that the changes work as intended.
+We write unit tests with pytest and store them in the `tests/` subdirectory.
+Run the tests with `python -m pytest`.
+
+If you change the **workflow**, please run the workflow with the test profile
+and make sure your new feature or bug fix works as intended.
+
+#### document
+
+If you have added a new feature or changed the API of an existing feature,
+you will likely need to update the documentation in `docs/`.
+
+### Commit and push your changes
+
+If you're not sure how often you should commit or what your commits should
+consist of, we recommend following the "atomic commits" principle where each
+commit contains one new feature, fix, or task.
+Learn more about atomic commits here:
+
+
+First, add the files that you changed to the staging area:
+
+```sh
+git add path/to/changed/files/
+```
+
+Then make the commit.
+Your commit message should follow the
+[Conventional Commits](https://www.conventionalcommits.org/en/v1.0.0/)
+specification.
+Briefly, each commit should start with one of the approved types such as
+`feat`, `fix`, `docs`, etc. followed by a description of the commit.
+Take a look at the [Conventional Commits specification](https://www.conventionalcommits.org/en/v1.0.0/#summary)
+for more detailed information about how to write commit messages.
+
+```sh
+git commit -m 'feat: create function for awesome feature'
+```
+
+pre-commit will enforce that your commit message and the code changes are
+styled correctly and will attempt to make corrections if needed.
+
+> Check for added large files..............................................Passed
+> Fix End of Files.........................................................Passed
+> Trim Trailing Whitespace.................................................Failed
+>
+> - hook id: trailing-whitespace
+> - exit code: 1
+> - files were modified by this hook
>
+> Fixing path/to/changed/files/file.txt
>
+> codespell................................................................Passed
+> style-files..........................................(no files to check)Skipped
+> readme-rmd-rendered..................................(no files to check)Skipped
+> use-tidy-description.................................(no files to check)Skipped
+
+In the example above, one of the hooks modified a file in the proposed commit,
+so the pre-commit check failed. You can run `git diff` to see the changes that
+pre-commit made and `git status` to see which files were modified. To proceed
+with the commit, re-add the modified file(s) and re-run the commit command:
+
+```sh
+git add path/to/changed/files/file.txt
+git commit -m 'feat: create function for awesome feature'
+```
+
+This time, all the hooks either passed or were skipped
+(e.g. hooks that only run on R code will not run if no R files were
+committed).
+When the pre-commit check is successful, the usual commit success message
+will appear after the pre-commit messages showing that the commit was created.
+
+> Check for added large files..............................................Passed
+> Fix End of Files.........................................................Passed
+> Trim Trailing Whitespace.................................................Passed
+> codespell................................................................Passed
+> style-files..........................................(no files to check)Skipped
+> readme-rmd-rendered..................................(no files to check)Skipped
+> use-tidy-description.................................(no files to check)Skipped
+> Conventional Commit......................................................Passed
> [iss-10 9ff256e] feat: create function for awesome feature
+> 1 file changed, 22 insertions(+), 3 deletions(-)
+
+Finally, push your changes to GitHub:
+
+```sh
+git push
+```
+
+If this is the first time you are pushing this branch, you may have to
+explicitly set the upstream branch:
+
+```sh
+git push --set-upstream origin iss-10
+```
+
+> Enumerating objects: 7, done.
+> Counting objects: 100% (7/7), done.
+> Delta compression using up to 10 threads
+> Compressing objects: 100% (4/4), done.
+> Writing objects: 100% (4/4), 648 bytes | 648.00 KiB/s, done.
+> Total 4 (delta 3), reused 0 (delta 0), pack-reused 0
+> remote: Resolving deltas: 100% (3/3), completed with 3 local objects.
+> remote:
+> remote: Create a pull request for 'iss-10' on GitHub by visiting:
+> remote: https://github.com/CCBR/XAVIER/pull/new/iss-10
+> remote:
+> To https://github.com/CCBR/XAVIER
>
> [new branch] iss-10 -> iss-10
+> branch 'iss-10' set up to track 'origin/iss-10'.
+
+We recommend pushing your commits often so they will be backed up on GitHub.
+You can view the files in your branch on GitHub at
+`https://github.com/CCBR/XAVIER/tree/`
+(replace `` with the actual name of your branch).
+
+### Create the PR
+
+Once your branch is ready, create a PR on GitHub:
+
+
+Select the branch you just pushed:
+
+
+
+Edit the PR title and description.
+The title should briefly describe the change.
+Follow the comments in the template to fill out the body of the PR, and
+you can delete the comments (everything between ``) as you go.
+Be sure to fill out the checklist, checking off items as you complete them or
+striking through any irrelevant items.
+When you're ready, click 'Create pull request' to open it.
+
+
+
+Optionally, you can mark the PR as a draft if you're not yet ready for it to
+be reviewed, then change it later when you're ready.
+
+### Wait for a maintainer to review your PR
+
+We will do our best to follow the tidyverse code review principles:
+.
+The reviewer may suggest that you make changes before accepting your PR in
+order to improve the code quality or style.
+If that's the case, continue to make changes in your branch and push them to
+GitHub, and they will appear in the PR.
+
+Once the PR is approved, the maintainer will merge it and the issue(s) the PR
+links will close automatically.
+Congratulations and thank you for your contribution!
+
+### After your PR has been merged
+
+After your PR has been merged, update your local clone of the repo by
+switching to the main branch and pulling the latest changes:
+
+```sh
+git checkout main
+git pull
+```
+
+It's a good idea to run `git pull` before creating a new branch so it will
+start from the most recent commits in main.
+
+## Helpful links for more information
+
+- [GitHub Flow](https://docs.github.com/en/get-started/using-github/github-flow)
+- [semantic versioning guidelines](https://semver.org/)
+- [changelog guidelines](https://keepachangelog.com/en/1.1.0/)
+- [tidyverse code review principles](https://code-review.tidyverse.org)
+- [reproducible examples](https://www.tidyverse.org/help/#reprex)
+- [nf-core extensions for VS Code](https://marketplace.visualstudio.com/items?itemName=nf-core.nf-core-extensionpack)
diff --git a/CHANGELOG.md b/CHANGELOG.md
index 46054c9..0d084dd 100644
--- a/CHANGELOG.md
+++ b/CHANGELOG.md
@@ -1,5 +1,8 @@
## XAVIER development version
+- New contributing guide available on GitHub and the documentation website. (#114, @kelly-sovacool)
+- New `xavier debug` subcommand to determine the base directory for debugging purposes. (#114, @kelly-sovacool)
+
## XAVIER 3.1.0
### new features
diff --git a/docs/contributing.md b/docs/contributing.md
new file mode 100644
index 0000000..773a7e5
--- /dev/null
+++ b/docs/contributing.md
@@ -0,0 +1,3 @@
+--8<-- ".github/CONTRIBUTING.md"
+
+
diff --git a/mkdocs.yml b/mkdocs.yml
index 130fb76..b61d5a6 100644
--- a/mkdocs.yml
+++ b/mkdocs.yml
@@ -113,4 +113,5 @@ nav:
- Output Files: pipeline-details/output.md
- FAQ:
- General Questions: faq/questions.md
+ - How to contribute: contributing.md
- License: license.md
diff --git a/pyproject.toml b/pyproject.toml
index 3e53d62..0f12601 100644
--- a/pyproject.toml
+++ b/pyproject.toml
@@ -42,7 +42,6 @@ dependencies = [
"Click >= 8.1.3",
"PySimpleGui < 5",
"snakemake >= 7.32, < 8",
- "snaketool-utils >= 0.0.5",
]
[project.optional-dependencies]
diff --git a/src/xavier/__main__.py b/src/xavier/__main__.py
index 7f607e0..af74eb7 100755
--- a/src/xavier/__main__.py
+++ b/src/xavier/__main__.py
@@ -659,8 +659,15 @@ def parsed_arguments():
help="Only display what remote resources would be pulled.",
)
+ subparser_debug = subparsers.add_parser(
+ "debug",
+ help="Debug the pipeline base directory.",
+ usage=argparse.SUPPRESS,
+ )
+
# Define handlers for each sub-parser
subparser_run.set_defaults(func=run)
+ subparser_debug.set_defaults(func=debug)
subparser_unlock.set_defaults(func=unlock)
subparser_cache.set_defaults(func=cache)
subparser_gui.set_defaults(func=launch_gui)
@@ -670,6 +677,11 @@ def parsed_arguments():
return args
+def debug(args):
+ print("BASE:", xavier_base())
+ print(get_version(debug=True))
+
+
def main():
# show helpful error message when no arguments given
if len(sys.argv) == 1:
diff --git a/src/xavier/util.py b/src/xavier/util.py
index 4f04bfa..d62a338 100644
--- a/src/xavier/util.py
+++ b/src/xavier/util.py
@@ -22,10 +22,13 @@ def xavier_base(*paths):
return str(basedir.joinpath(*paths))
-def get_version():
+def get_version(debug=False):
"""Get the current version
@return version
"""
- with open(xavier_base("VERSION"), "r") as vfile:
+ version_file = xavier_base("VERSION")
+ if debug:
+ print("VERSION FILE:", version_file)
+ with open(version_file, "r") as vfile:
version = f"v{vfile.read().strip()}"
return version
diff --git a/tests/test_cli.py b/tests/test_cli.py
index 2196e3f..99abb44 100644
--- a/tests/test_cli.py
+++ b/tests/test_cli.py
@@ -33,6 +33,11 @@ def test_help():
assert "XAVIER" in shell_run("./bin/xavier --help")
+def test_debug():
+ out = shell_run("./bin/xavier debug")
+ assert all(["xavier (v" in out, "BASE: /" in out, "VERSION FILE: /" in out])
+
+
def test_dryrun_targets():
if get_hpcname() == "biowulf":
output_human, config_human = run_in_temp(f"{xavier_run} --genome hg38")