From be4724f06511ed17fd4d820d1c29b8f74ede6ff6 Mon Sep 17 00:00:00 2001 From: Altana Namsaraeva <99650244+namsaraeva@users.noreply.github.com> Date: Tue, 3 Dec 2024 13:22:25 +0100 Subject: [PATCH 1/8] initial CONTRIBUTING.md --- docs/CONTRIBUTING.md | 109 +++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 109 insertions(+) create mode 100644 docs/CONTRIBUTING.md diff --git a/docs/CONTRIBUTING.md b/docs/CONTRIBUTING.md new file mode 100644 index 00000000..1a375c0c --- /dev/null +++ b/docs/CONTRIBUTING.md @@ -0,0 +1,109 @@ +# Contributing guide + +Scanpy provides extensive [developer documentation][scanpy developer guide], most of which applies to this repo, too. +This document will not reproduce the entire content from there. Instead, it aims at summarizing the most important +information to get you started on contributing. + +We assume that you are already familiar with git and with making pull requests on GitHub. If not, please refer +to the [scanpy developer guide][]. + +## Installing dev dependencies + +In addition to the packages needed to _use_ this package, you need additional python packages to _run tests_ and _build +the documentation_. It's easy to install them using `pip`: + +```bash +git clone https://github.com/MannLabs/scPortrait +cd scPortrait +pip install -e '.[dev]' +``` + +## Code-style + +This project uses [pre-commit][] to enforce consistent code-styles. On every commit, pre-commit checks will either +automatically fix issues with the code, or raise an error message. + +To enable pre-commit locally, simply run + +```bash +pre-commit install +``` + +in the root of the repository. Pre-commit will automatically download all dependencies when it is run for the first time. + +Alternatively, you can rely on the [pre-commit.ci][] service enabled on GitHub. If you didn't run `pre-commit` before +pushing changes to GitHub it will automatically commit fixes to your pull request, or show an error message. + +If pre-commit.ci added a commit on a branch you still have been working on locally, simply use + +```bash +git pull --rebase +``` + +to integrate the changes into yours. +While the [pre-commit.ci][] is useful, we strongly encourage installing and running pre-commit locally first to understand its usage. + +## Writing tests + +```{note} +Remember to first install the package with pip install -e '.[dev]' +``` +TBD + +## Publishing a release + +### Updating the version number + +Before making a release, you need to update the version number. Please adhere to [Semantic Versioning][semver], in brief + +> Given a version number MAJOR.MINOR.PATCH, increment the: +> +> 1. MAJOR version when you make incompatible API changes, +> 2. MINOR version when you add functionality in a backwards compatible manner, and +> 3. PATCH version when you make backwards compatible bug fixes. +> +> Additional labels for pre-release and build metadata are available as extensions to the MAJOR.MINOR.PATCH format. + +Once you are done, run + +``` +git push --tags +``` + +to publish the created tag on GitHub. + +### Building and publishing the package on PyPI + +TBD + +## Writing documentation + +Please write documentation for new or changed features and use-cases. This project uses [sphinx][] with the following features: + +- Google-style docstrings +- TBD + +See the [scanpy developer docs](https://scanpy.readthedocs.io/en/latest/dev/documentation.html) for more information +on how to write documentation. + +### Tutorials with jupyter notebooks + +TBD + +#### Building the docs locally + +```bash +cd docs +# TBD +``` + + + +[scanpy developer guide]: https://scanpy.readthedocs.io/en/latest/dev/index.html +[cookiecutter-scverse-instance]: https://cookiecutter-scverse-instance.readthedocs.io/en/latest/template_usage.html +[github quickstart guide]: https://docs.github.com/en/get-started/quickstart/create-a-repo?tool=webui +[pre-commit.ci]: https://pre-commit.ci/ +[pre-commit]: https://pre-commit.com/ +[sphinx]: https://www.sphinx-doc.org/en/master/ +[sphinx autodoc typehints]: https://github.com/tox-dev/sphinx-autodoc-typehints + From dafdc8fad372b431ed97f161587061ecbc38ef0c Mon Sep 17 00:00:00 2001 From: Altana Namsaraeva <99650244+namsaraeva@users.noreply.github.com> Date: Tue, 3 Dec 2024 13:31:48 +0100 Subject: [PATCH 2/8] Create pull_request_template.md --- .github/pull_request_template.md | 22 ++++++++++++++++++++++ 1 file changed, 22 insertions(+) create mode 100644 .github/pull_request_template.md diff --git a/.github/pull_request_template.md b/.github/pull_request_template.md new file mode 100644 index 00000000..3bbf5221 --- /dev/null +++ b/.github/pull_request_template.md @@ -0,0 +1,22 @@ + + +**PR Checklist** + + + +- [ ] This comment contains a description of changes (with reason) +- [ ] Referenced issue is linked +- [ ] If you've fixed a bug or added code that should be tested, add tests! +- [ ] Documentation in `docs` is updated + +**Description of changes** + + + +**Technical details** + + + +**Additional context** + + From 0f39f0784ef267c4ae7ae530982f71d6bb807ee8 Mon Sep 17 00:00:00 2001 From: namsaraeva Date: Tue, 3 Dec 2024 13:45:02 +0100 Subject: [PATCH 3/8] fix pre-commit --- .github/pull_request_template.md | 8 ++++---- docs/CONTRIBUTING.md | 1 - 2 files changed, 4 insertions(+), 5 deletions(-) diff --git a/.github/pull_request_template.md b/.github/pull_request_template.md index 3bbf5221..60fc7391 100644 --- a/.github/pull_request_template.md +++ b/.github/pull_request_template.md @@ -4,10 +4,10 @@ -- [ ] This comment contains a description of changes (with reason) -- [ ] Referenced issue is linked -- [ ] If you've fixed a bug or added code that should be tested, add tests! -- [ ] Documentation in `docs` is updated +- [ ] This comment contains a description of changes (with reason) +- [ ] Referenced issue is linked +- [ ] If you've fixed a bug or added code that should be tested, add tests! +- [ ] Documentation in `docs` is updated **Description of changes** diff --git a/docs/CONTRIBUTING.md b/docs/CONTRIBUTING.md index 1a375c0c..4db9864a 100644 --- a/docs/CONTRIBUTING.md +++ b/docs/CONTRIBUTING.md @@ -106,4 +106,3 @@ cd docs [pre-commit]: https://pre-commit.com/ [sphinx]: https://www.sphinx-doc.org/en/master/ [sphinx autodoc typehints]: https://github.com/tox-dev/sphinx-autodoc-typehints - From 719bcda33f928e68cf5bcda2f7a5d74e2b550b12 Mon Sep 17 00:00:00 2001 From: Altana Namsaraeva <99650244+namsaraeva@users.noreply.github.com> Date: Tue, 3 Dec 2024 13:54:14 +0100 Subject: [PATCH 4/8] Update README.md --- README.md | 7 ++++++- 1 file changed, 6 insertions(+), 1 deletion(-) diff --git a/README.md b/README.md index 5f132233..d1cf431a 100644 --- a/README.md +++ b/README.md @@ -38,4 +38,9 @@ bioRxiv 2023.06.01.542416; doi: https://doi.org/10.1101/2023.06.01.542416 ## Contributing -If you like this software, you can give us a star to boost our visibility! All direct contributions are also welcome. Feel free to post a new [issue](https://github.com/MannLabs/alphapeptstats/issues) or clone the repository and create a [pull request](https://github.com/MannLabs/scPortrait/pulls) with a new branch. For an even more interactive participation, check out the [discussions](https://github.com/MannLabs/scPortrait/discussions). +If you like this software, consider giving us a star to boost our visibility! For detailed guidelines on how to contribute, please refer to our [CONTRIBUTING.md](./docs/CONTRIBUTING.md). + +We welcome all types of contributions! You can: +- Post a new [issue](https://github.com/MannLabs/alphapeptstats/issues) if you encounter a bug or have a feature request. +- Clone the repository, create a new branch, and submit a [pull request](https://github.com/MannLabs/scPortrait/pulls). +- Join the conversation in our [discussions](https://github.com/MannLabs/scPortrait/discussions) for more interactive participation. From 5bda74e4f3cea80fa37b8e6a2ebbb809db1d0a73 Mon Sep 17 00:00:00 2001 From: namsaraeva Date: Tue, 3 Dec 2024 13:58:57 +0100 Subject: [PATCH 5/8] fix pre-commit --- README.md | 3 ++- 1 file changed, 2 insertions(+), 1 deletion(-) diff --git a/README.md b/README.md index d1cf431a..22bfa2d3 100644 --- a/README.md +++ b/README.md @@ -38,9 +38,10 @@ bioRxiv 2023.06.01.542416; doi: https://doi.org/10.1101/2023.06.01.542416 ## Contributing -If you like this software, consider giving us a star to boost our visibility! For detailed guidelines on how to contribute, please refer to our [CONTRIBUTING.md](./docs/CONTRIBUTING.md). +If you like this software, consider giving us a star to boost our visibility! For detailed guidelines on how to contribute, please refer to our [CONTRIBUTING.md](./docs/CONTRIBUTING.md). We welcome all types of contributions! You can: + - Post a new [issue](https://github.com/MannLabs/alphapeptstats/issues) if you encounter a bug or have a feature request. - Clone the repository, create a new branch, and submit a [pull request](https://github.com/MannLabs/scPortrait/pulls). - Join the conversation in our [discussions](https://github.com/MannLabs/scPortrait/discussions) for more interactive participation. From 32d7c36567ba77831bc94fbdc44b4c2f45a95a52 Mon Sep 17 00:00:00 2001 From: namsaraeva Date: Thu, 5 Dec 2024 12:05:54 +0100 Subject: [PATCH 6/8] remove irrelevant text --- .github/pull_request_template.md | 1 - docs/CONTRIBUTING.md | 11 ----------- 2 files changed, 12 deletions(-) diff --git a/.github/pull_request_template.md b/.github/pull_request_template.md index 60fc7391..ddc4e22d 100644 --- a/.github/pull_request_template.md +++ b/.github/pull_request_template.md @@ -6,7 +6,6 @@ - [ ] This comment contains a description of changes (with reason) - [ ] Referenced issue is linked -- [ ] If you've fixed a bug or added code that should be tested, add tests! - [ ] Documentation in `docs` is updated **Description of changes** diff --git a/docs/CONTRIBUTING.md b/docs/CONTRIBUTING.md index 4db9864a..8dbf7be3 100644 --- a/docs/CONTRIBUTING.md +++ b/docs/CONTRIBUTING.md @@ -72,10 +72,6 @@ git push --tags to publish the created tag on GitHub. -### Building and publishing the package on PyPI - -TBD - ## Writing documentation Please write documentation for new or changed features and use-cases. This project uses [sphinx][] with the following features: @@ -90,13 +86,6 @@ on how to write documentation. TBD -#### Building the docs locally - -```bash -cd docs -# TBD -``` - [scanpy developer guide]: https://scanpy.readthedocs.io/en/latest/dev/index.html From 9757f2fc286ab3dcb598321271f9f5794ac7a714 Mon Sep 17 00:00:00 2001 From: Altana Namsaraeva <99650244+namsaraeva@users.noreply.github.com> Date: Wed, 11 Dec 2024 10:25:19 +0100 Subject: [PATCH 7/8] draft contributing.md --- docs/CONTRIBUTING.md | 36 ++++-------------------------------- 1 file changed, 4 insertions(+), 32 deletions(-) diff --git a/docs/CONTRIBUTING.md b/docs/CONTRIBUTING.md index 8dbf7be3..1d7501d4 100644 --- a/docs/CONTRIBUTING.md +++ b/docs/CONTRIBUTING.md @@ -43,48 +43,20 @@ git pull --rebase to integrate the changes into yours. While the [pre-commit.ci][] is useful, we strongly encourage installing and running pre-commit locally first to understand its usage. -## Writing tests - -```{note} -Remember to first install the package with pip install -e '.[dev]' -``` -TBD - -## Publishing a release - -### Updating the version number - -Before making a release, you need to update the version number. Please adhere to [Semantic Versioning][semver], in brief - -> Given a version number MAJOR.MINOR.PATCH, increment the: -> -> 1. MAJOR version when you make incompatible API changes, -> 2. MINOR version when you add functionality in a backwards compatible manner, and -> 3. PATCH version when you make backwards compatible bug fixes. -> -> Additional labels for pre-release and build metadata are available as extensions to the MAJOR.MINOR.PATCH format. - -Once you are done, run - -``` -git push --tags -``` - -to publish the created tag on GitHub. - ## Writing documentation Please write documentation for new or changed features and use-cases. This project uses [sphinx][] with the following features: - Google-style docstrings -- TBD +- example code +- automatic building with Sphinx See the [scanpy developer docs](https://scanpy.readthedocs.io/en/latest/dev/documentation.html) for more information -on how to write documentation. +on how to write documentation. (remove later) ### Tutorials with jupyter notebooks -TBD +link to notebooks repo From 5150b865193a2657d6a489bb051c6413bb373386 Mon Sep 17 00:00:00 2001 From: namsaraeva Date: Fri, 13 Dec 2024 16:35:45 +0100 Subject: [PATCH 8/8] add some changes --- docs/CONTRIBUTING.md | 10 ++++++---- 1 file changed, 6 insertions(+), 4 deletions(-) diff --git a/docs/CONTRIBUTING.md b/docs/CONTRIBUTING.md index 1d7501d4..b56fbfc9 100644 --- a/docs/CONTRIBUTING.md +++ b/docs/CONTRIBUTING.md @@ -41,22 +41,22 @@ git pull --rebase ``` to integrate the changes into yours. + While the [pre-commit.ci][] is useful, we strongly encourage installing and running pre-commit locally first to understand its usage. ## Writing documentation Please write documentation for new or changed features and use-cases. This project uses [sphinx][] with the following features: -- Google-style docstrings +- Google-style docstrings, where the __init__ method should be documented in its own docstring, not at the class level. - example code - automatic building with Sphinx -See the [scanpy developer docs](https://scanpy.readthedocs.io/en/latest/dev/documentation.html) for more information -on how to write documentation. (remove later) +Refer to [sphinx google style docstrings][] for detailed information on writing documentation. ### Tutorials with jupyter notebooks -link to notebooks repo +The tutorials for this project are hosted in a dedicated repository: [scPortrait Notebooks](https://github.com/MannLabs/scPortrait-notebooks). @@ -67,3 +67,5 @@ link to notebooks repo [pre-commit]: https://pre-commit.com/ [sphinx]: https://www.sphinx-doc.org/en/master/ [sphinx autodoc typehints]: https://github.com/tox-dev/sphinx-autodoc-typehints +[sphinx google style docstrings]: https://sphinxcontrib-napoleon.readthedocs.io/en/latest/example_google.html +[scPortrait Notebooks]: (https://github.com/MannLabs/scPortrait-notebooks)