From 55fad8de7ac7498717214a129c864a8158a41042 Mon Sep 17 00:00:00 2001 From: Degbelo Date: Thu, 11 Jun 2026 09:54:13 -0500 Subject: [PATCH 1/2] Improve contributing tutorial documentation - Fix Dataset API example to use DatasetSchema instead of plain dict - Add pre-flight environment checklist to Prerequisites section - Add note about PAT workflow scope requirement in Step 7 Closes #480 --- docs/contributing/index.rst | 29 +++++++++++++++++++++++++++-- 1 file changed, 27 insertions(+), 2 deletions(-) diff --git a/docs/contributing/index.rst b/docs/contributing/index.rst index f47e935b0..82897c1ce 100644 --- a/docs/contributing/index.rst +++ b/docs/contributing/index.rst @@ -47,6 +47,18 @@ SPRAS contributions: or `10 minutes to pandas `__ + + + Before getting started, verify your environment is ready with these checks: + +.. code:: bash + + docker --version + docker run hello-world + docker login + conda --version + git --version + ************************************************* Step 0: Fork the repository and create a branch ************************************************* @@ -202,8 +214,9 @@ and explore the nodes and interactome. .. code:: python > from spras.dataset import Dataset - > dataset_dict = {'label': 'data0', 'node_files': ['node-prizes.txt', 'sources.txt', 'targets.txt'], 'edge_files': ['network.txt'], 'other_files': [], 'data_dir': 'input'} - > data = Dataset(dataset_dict) + > from spras.config.dataset import DatasetSchema + > dataset_schema = DatasetSchema(label='data0', node_files=['node-prizes.txt', 'sources.txt', 'targets.txt'], edge_files=['network.txt'], other_files=[], data_dir='input') + > data = Dataset(dataset_schema) > data.node_table.head() NODEID prize active sources targets 0 C 5.7 True NaN True @@ -416,6 +429,16 @@ branch and create a pull request. Make sure to commit all of the new and modified files and push them to the ``local-neighborhood`` branch on your fork. + +.. note:: + + If you are using HTTPS to push and your commit touches files in + ``.github/workflows/``, your PAT must have both ``repo`` and + ``workflow`` scopes. A PAT with ``repo`` scope only will be rejected + with a non-obvious error. SSH push works without this restriction. + + + The SPRAS maintainers will review the pull request and provide feedback and suggested changes. If you are not already in communication with them, you can open a `GitHub issue @@ -425,6 +448,8 @@ feedback. However, once the pull request has been approved, it will ``main`` branch of the fork stays synchronized with the ``main`` branch of the main SPRAS repository. + + *********************************************************************** General steps for contributing a new pathway reconstruction algorithm *********************************************************************** From 8952503cfe53e5c8c254af4b1f93a2e295447f84 Mon Sep 17 00:00:00 2001 From: Degbelo Date: Thu, 9 Jul 2026 09:32:50 -0500 Subject: [PATCH 2/2] Address PR review comments: fix indentation, add expected output, move PAT note to Step 5, add SPRAS env check, remove extra whitespace --- docs/contributing/index.rst | 27 ++++++++++++--------------- 1 file changed, 12 insertions(+), 15 deletions(-) diff --git a/docs/contributing/index.rst b/docs/contributing/index.rst index 82897c1ce..2b1e6650c 100644 --- a/docs/contributing/index.rst +++ b/docs/contributing/index.rst @@ -47,9 +47,8 @@ SPRAS contributions: or `10 minutes to pandas `__ - - - Before getting started, verify your environment is ready with these checks: +Before getting started, verify your environment is ready with these +checks: .. code:: bash @@ -58,6 +57,9 @@ SPRAS contributions: docker login conda --version git --version + python -c "import spras; print('SPRAS import successful')" + +If the commands above run without errors, your environment is ready. ************************************************* Step 0: Fork the repository and create a branch @@ -344,6 +346,13 @@ its contents before rerunning the Snakemake command. Step 5: Add Local Neighborhood to the tests ********************************************* +.. note:: + + These tests modify files in ``.github/workflows/``. If you push over + HTTPS using a Personal Access Token, make sure the token has + permission to modify GitHub Actions workflows. Otherwise, GitHub may + reject the push. SSH push works without this restriction. + Add test functions to the test file ``test/test_ln.py``. This file already has existing tests to test the correctness of the Local Neighborhood implementation that was added to the Docker image. The new @@ -429,16 +438,6 @@ branch and create a pull request. Make sure to commit all of the new and modified files and push them to the ``local-neighborhood`` branch on your fork. - -.. note:: - - If you are using HTTPS to push and your commit touches files in - ``.github/workflows/``, your PAT must have both ``repo`` and - ``workflow`` scopes. A PAT with ``repo`` scope only will be rejected - with a non-obvious error. SSH push works without this restriction. - - - The SPRAS maintainers will review the pull request and provide feedback and suggested changes. If you are not already in communication with them, you can open a `GitHub issue @@ -448,8 +447,6 @@ feedback. However, once the pull request has been approved, it will ``main`` branch of the fork stays synchronized with the ``main`` branch of the main SPRAS repository. - - *********************************************************************** General steps for contributing a new pathway reconstruction algorithm ***********************************************************************