Merge pull request #1520 from Sage-Bionetworks/develop

v24.10.2

CONTRIBUTION.md

@@ -4,78 +4,78 @@ When contributing to this repository, please first discuss the change you wish t
 
 Please note we have a [code of conduct](CODE_OF_CONDUCT.md), please follow it in all your interactions with the project.
 
-## How to contribute
+## How to report bugs or feature requests
 
-### Reporting bugs or feature requests
-
-You can use [Sage Bionetwork's FAIR Data service desk](https://sagebionetworks.jira.com/servicedesk/customer/portal/5/group/8) to **create bug and feature requests**. Providing enough details to the developers to verify and troubleshoot your issue is paramount:
+You can **create bug and feature requests** through [Sage Bionetwork's FAIR Data service desk](https://sagebionetworks.jira.com/servicedesk/customer/portal/5/group/8). Providing enough details to the developers to verify and troubleshoot your issue is paramount:
 - **Provide a clear and descriptive title as well as a concise summary** of the issue to identify the problem.
 - **Describe the exact steps which reproduce the problem** in as many details as possible.
 - **Describe the behavior you observed after following the steps** and point out what exactly is the problem with that behavior.
 - **Explain which behavior you expected to see** instead and why.
 - **Provide screenshots of the expected or actual behaviour** where applicable.
 
-### General contribution instructions
+## How to contribute code
 
-1. Follow the [Github docs](https://help.github.com/articles/fork-a-repo/) to make a copy (a fork) of the repository to your own Github account.
-2. [Clone the forked repository](https://docs.github.com/en/github/creating-cloning-and-archiving-repositories/cloning-a-repository-from-github/cloning-a-repository) to your local machine so you can begin making changes.
-3. Make sure this repository is set as the [upstream remote repository](https://docs.github.com/en/github/collaborating-with-pull-requests/working-with-forks/configuring-a-remote-for-a-fork) so you are able to fetch the latest commits.
-4. Push all your changes to the `develop` branch of the forked repository.
+### The development environment setup
 
-*Note*: Make sure you have you have the latest version of the `develop` branch on your local machine.
+For setting up your environment, please follow the instructions in the `README.md` under `Installation Guide For: Contributors`.
 
-```
-git checkout develop
-git pull upstream develop
-```
+### The development workflow
 
-5. Create pull requests to the upstream repository.
+For new features, bugs, enhancements:
 
-### The development lifecycle
+#### 1. Branch Setup
+* Pull the latest code from the develop branch in the upstream repository.
+* Checkout a new branch formatted like so: `develop-<feature/fix-name>` from the develop branch
 
-1. Pull the latest content from the `develop` branch of this central repository (not your fork).
-2. Create a branch off the `develop` branch. Name the branch appropriately, either briefly summarizing the bug (ex., `spatil/add-restapi-layer`) or feature or simply use the issue number in the name (ex., `spatil/issue-414-fix`).
-3. After completing work and testing locally, push the code to the appropriate branch on your fork.
-4. In Github, create a pull request from the bug/feature branch of your fork to the `develop` branch of the central repository.
+#### 2. Development Workflow
+* Develop on your new branch.
+* Ensure pyproject.toml and poetry.lock files are compatible with your environment.
+* Add changed files for tracking and commit changes using [best practices](https://www.perforce.com/blog/vcs/git-best-practices-git-commit)
+* Have granular commits: not “too many” file changes, and not hundreds of code lines of changes
+* You can choose to create a draft PR if you prefer to develop this way
 
-> A Sage Bionetworks engineer must review and accept your pull request. A code review (which happens with both the contributor and the reviewer present) is required for contributing.
+#### 3. Branch Management
+* Push code to `develop-<feature/fix-name>` in upstream repo:
+  ```
+  git push <upstream> develop-<feature/fix-name>
+  ```
+* Branch off `develop-<feature/fix-name>` if you need to work on multiple features associated with the same code base
+* After feature work is complete and before creating a PR to the develop branch in upstream
+    a. ensure that code runs locally
+    b. test for logical correctness locally
+    c. run `pre-commit` to style code if the hook is not installed
+    c. wait for git workflow to complete (e.g. tests are run) on github
 
-### Development environment setup
+#### 4. Pull Request and Review
+* Create a PR from `develop-<feature/fix-name>` into the develop branch of the upstream repo
+* Request a code review on the PR
+* Once code is approved merge in the develop branch. We suggest creating a merge commit for a cleaner commit history on the `develop` branch.
+* Once the actions pass on the main branch, delete the `develop-<feature/fix-name>` branch
 
-1. Install [package dependencies](https://sage-schematic.readthedocs.io/en/develop/README.html#installation-requirements-and-pre-requisites).
-2. Clone the `schematic` package repository.
+### Updating readthedocs documentation
+1. Navigate to the docs directory.
+2. Run make html to regenerate the build after changes.
+3. Contact the development team to publish the updates.
 
-```
-git clone https://github.com/Sage-Bionetworks/schematic.git
-```
+*Helpful resources*:
 
-3. [Create and activate](https://sage-schematic.readthedocs.io/en/develop/README.html#virtual-environment-setup) a virtual environment.
-4. Run the following commands to build schematic and install the package along with all of its dependencies:
+1. [Getting started with Sphinx](https://www.sphinx-doc.org/en/master/usage/quickstart.html)
+2. [Installing Sphinx](https://www.sphinx-doc.org/en/master/usage/installation.html)
 
-```
-cd schematic  # change directory to schematic
-git checkout develop  # switch to develop branch of schematic
-poetry build # build source and wheel archives
-pip install dist/schematicpy-x.y.z-py3-none-any.whl  # install wheel file
-```
-
-*Note*: Use the appropriate version number (based on the version of the codebase you are pulling) while installing the wheel file above.
-
-5. [Obtain](https://sage-schematic.readthedocs.io/en/develop/README.html#obtain-google-credentials-file-s) appropriate Google credentials file(s).
-6. [Obtain and Fill in](https://sage-schematic.readthedocs.io/en/develop/README.html#fill-in-configuration-file-s) the `config.yml` file and the `.synapseConfig` file as well as described in the `Fill in Configuration File(s)` part of the documentation.
-7. [Run](https://docs.pytest.org/en/stable/usage.html) the test suite.
+### Update toml file and lock file
+If you install external libraries by using `poetry add <name of library>`, please make sure that you include `pyproject.toml` and `poetry.lock` file in your commit.
 
-*Note*: To ensure that all tests run successfully, contact your DCC liason and request to be added to the `schematic-dev` [team](https://www.synapse.org/#!Team:3419888) on Synapse.
+### Code style
 
-8. To test new changes made to any of the modules within `schematic`, do the following:
+To ensure consistent code formatting across the project, we use the `pre-commit` hook. You can manually run `pre-commit` across the respository before making a pull request like so:
 
 ```
-# make changes to any files or modules
-pip uninstall schematicpy  # uninstall package
-poetry build
-pip install dist/schematicpy-x.y.z-py3-none-any.whl  # install wheel file
+pre-commit run --all-files
 ```
 
+Further, please consult the [Google Python style guide](http://google.github.io/styleguide/pyguide.html) prior to contributing code to this project.
+Be consistent and follow existing code conventions and spirit.
+
 ## Release process
 
 Once the code has been merged into the `develop` branch on this repo, there are two processes that need to be completed to ensure a _release_ is complete.
@@ -109,12 +109,13 @@ poetry publish  # publish the package to PyPI
 
 > You'll need to [register](https://pypi.org/account/register/) for a PyPI account before uploading packages to the package index. Similarly for [Test PyPI](https://test.pypi.org/account/register/) as well.
 
-## Testing
+## Testing 
 
-All code added to the client must have tests. The Python client uses pytest to run tests. The test code is located in the [tests](https://github.com/Sage-Bionetworks/schematic/tree/develop-docs-update/tests) subdirectory.
+* All new code must include tests.
 
-You can run the test suite in the following way:
+* Tests are written using pytest and are located in the [tests/](https://github.com/Sage-Bionetworks/schematic/tree/develop/tests) subdirectory.
 
+* Run tests with:
 ```
 pytest -vs tests/
 ```
@@ -128,7 +129,3 @@ pytest -vs tests/
 5. Once the PR is merged, leave the original copies on Synapse to maintain support for feature branches that were forked from `develop` before your update.
    - If the old copies are problematic and need to be removed immediately (_e.g._ contain sensitive data), proceed with the deletion and alert the other contributors that they need to merge the latest `develop` branch into their feature branches for their tests to work.
 
-## Code style
-
-* Please consult the [Google Python style guide](http://google.github.io/styleguide/pyguide.html) prior to contributing code to this project.
-* Be consistent and follow existing code conventions and spirit.