From 18725e4f16b50af7900a478c96cb8277162a4304 Mon Sep 17 00:00:00 2001 From: Kelly Sovacool Date: Tue, 17 Sep 2024 11:02:41 -0400 Subject: [PATCH 1/6] fix: add debug command to print the base dir --- src/xavier/__main__.py | 12 ++++++++++++ src/xavier/util.py | 7 +++++-- 2 files changed, 17 insertions(+), 2 deletions(-) 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 From 6ea9a504c5e5a40010a6c8ad2c4f7ddb860691e1 Mon Sep 17 00:00:00 2001 From: Kelly Sovacool Date: Tue, 17 Sep 2024 11:09:19 -0400 Subject: [PATCH 2/6] docs: add contrib guide --- .github/CONTRIBUTING.md | 262 ++++++++++++++++++++++++++++++++++++++++ CHANGELOG.md | 2 + docs/contributing.md | 3 + mkdocs.yml | 1 + 4 files changed, 268 insertions(+) create mode 100644 .github/CONTRIBUTING.md create mode 100644 docs/contributing.md diff --git a/.github/CONTRIBUTING.md b/.github/CONTRIBUTING.md new file mode 100644 index 0000000..6071d3b --- /dev/null +++ b/.github/CONTRIBUTING.md @@ -0,0 +1,262 @@ +# Contributing to TOOL_NAME + +## 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 +TOOL_NAME. + +![GitHub Flow diagram](https://raw.githubusercontent.com/CCBR/CCBR_NextflowTemplate/main/.github/img/GitHub-Flow_bg-white.png) + +### 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/TOOL_NAME +``` + +> Cloning into 'TOOL_NAME'...
+> 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 TOOL_NAME +``` + +### If this is your first time cloning the repo, you may need to install dependencies + +- Install nextflow 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/TOOL_NAME/pull/new/iss-10
+> remote:
+> To https://github.com/CCBR/TOOL_NAME
>
> [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/TOOL_NAME/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: + +![Create a new PR from your branch](https://raw.githubusercontent.com/CCBR/CCBR_NextflowTemplate/main/.github/img/new-PR.png) + +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. + +![Open the PR after editing the title and description](https://raw.githubusercontent.com/CCBR/CCBR_NextflowTemplate/main/.github/img/create-PR.png) + +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..eb43dd3 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -1,5 +1,7 @@ ## XAVIER development version +- minor documentation improvements. + ## 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 From baefe286d855da3328549563de01c10edcec0273 Mon Sep 17 00:00:00 2001 From: Kelly Sovacool Date: Tue, 17 Sep 2024 16:38:15 -0400 Subject: [PATCH 3/6] chore: remove unneeded snaketool-utils pkg --- pyproject.toml | 1 - 1 file changed, 1 deletion(-) 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] From cbccd43b1feff022790106381f86e19a10facbe1 Mon Sep 17 00:00:00 2001 From: Kelly Sovacool Date: Thu, 19 Sep 2024 13:17:52 -0400 Subject: [PATCH 4/6] docs: replace vars in contrib template --- .github/CONTRIBUTING.md | 20 ++++++++++---------- 1 file changed, 10 insertions(+), 10 deletions(-) diff --git a/.github/CONTRIBUTING.md b/.github/CONTRIBUTING.md index 6071d3b..6f7efed 100644 --- a/.github/CONTRIBUTING.md +++ b/.github/CONTRIBUTING.md @@ -1,4 +1,4 @@ -# Contributing to TOOL_NAME +# Contributing to XAVIER ## Proposing changes with issues @@ -15,7 +15,7 @@ so others will know you're working on it. 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 -TOOL_NAME. +XAVIER. ![GitHub Flow diagram](https://raw.githubusercontent.com/CCBR/CCBR_NextflowTemplate/main/.github/img/GitHub-Flow_bg-white.png) @@ -28,10 +28,10 @@ Otherwise, you will first need to the repo and clone your fork. You only need to do this step once. ```sh -git clone https://github.com/CCBR/TOOL_NAME +git clone https://github.com/CCBR/XAVIER ``` -> Cloning into 'TOOL_NAME'...
+> Cloning into 'XAVIER'...
> remote: Enumerating objects: 1136, done.
> remote: Counting objects: 100% (463/463), done.
> remote: Compressing objects: 100% (357/357), done.
@@ -40,12 +40,12 @@ git clone https://github.com/CCBR/TOOL_NAME > Resolving deltas: 100% (530/530), done.
```sh -cd TOOL_NAME +cd XAVIER ``` ### If this is your first time cloning the repo, you may need to install dependencies -- Install nextflow and singularity or docker if needed (biowulf already has these available as modules). +- Install snakemake and singularity or docker if needed (biowulf already has these available as modules). - Install the python dependencies with pip @@ -194,20 +194,20 @@ git push --set-upstream origin iss-10 > 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/TOOL_NAME/pull/new/iss-10
+> remote: https://github.com/CCBR/XAVIER/pull/new/iss-10
> remote:
-> To https://github.com/CCBR/TOOL_NAME
>
> [new branch] iss-10 -> iss-10
+> 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/TOOL_NAME/tree/` +`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: From 713d10147ca6174182a270390122cbe2c2aad7d8 Mon Sep 17 00:00:00 2001 From: Kelly Sovacool Date: Thu, 19 Sep 2024 13:20:34 -0400 Subject: [PATCH 5/6] chore: update changelog --- CHANGELOG.md | 3 ++- 1 file changed, 2 insertions(+), 1 deletion(-) diff --git a/CHANGELOG.md b/CHANGELOG.md index eb43dd3..0d084dd 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -1,6 +1,7 @@ ## XAVIER development version -- minor documentation improvements. +- 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 From 5db9130a657bb1801b125a27ffd22353dce35933 Mon Sep 17 00:00:00 2001 From: Kelly Sovacool Date: Thu, 19 Sep 2024 13:23:22 -0400 Subject: [PATCH 6/6] test: add basic test for debug subcommand --- tests/test_cli.py | 5 +++++ 1 file changed, 5 insertions(+) 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")