Skip to content

Commit 91ce5d9

Browse files
authored
[GEN-2380] Update docs (#623)
* update to match current workflows * test dynamically getting feature branch image * add docker env setup, standardize commands and remove dedundancy * add docker section * shift docker development and make it sage vs external specific between readme and contributing docs
1 parent 0bf8d69 commit 91ce5d9

File tree

3 files changed

+226
-66
lines changed

3 files changed

+226
-66
lines changed

.devcontainer/devcontainer.json

Lines changed: 0 additions & 6 deletions
This file was deleted.

CONTRIBUTING.md

Lines changed: 22 additions & 38 deletions
Original file line numberDiff line numberDiff line change
@@ -3,6 +3,22 @@
33

44
We welcome all contributions! Please head to [issues](https://github.com/Sage-Bionetworks/Genie/issues) to either file any bugs/feature requests or find a task you want to assist with. Make sure to assign yourself the task if you decide to work on it.
55

6+
## Table of Contents
7+
8+
- [Coding Style](#coding-style)
9+
- [The Development Life Cycle](#the-development-life-cycle)
10+
- [Fork and clone this repository](#fork-and-clone-this-repository)
11+
- [Install development dependencies](#install-development-dependencies)
12+
- [Developing](#developing)
13+
- [Testing](#testing)
14+
- [Running tests](#running-tests)
15+
- [Tests in Python](#tests-in-python)
16+
- [Tests in R](#tests-in-r)
17+
- [Test Development](#test-development)
18+
- [Mock Testing](#mock-testing)
19+
- [Release Procedure (For Package Maintainers)](#release-procedure-for-package-maintainers)
20+
- [Contributing to the docs](#contributing-to-the-docs)
21+
622
## Coding Style
723

824
This package uses `flake8` - it's settings are described in [setup.cfg](setup.cfg). The code in this package is also automatically formatted by `black` for consistency.
@@ -23,22 +39,7 @@ This package uses `flake8` - it's settings are described in [setup.cfg](setup.cf
2339
2440
### Install development dependencies
2541
26-
This will install all the dependencies of the package including the active branch of `Genie`. We highly recommend that you leverage some form of python version management like [pyenv](https://github.com/pyenv/pyenv) or [anaconda](https://www.anaconda.com/products/individual). There are two ways you can install the dependencies for this package.
27-
28-
#### pip
29-
This is the more traditional way of installing dependencies. Follow instructions [here](https://pip.pypa.io/en/stable/installation/) to learn how to install pip.
30-
31-
```
32-
pip install -r requirements-dev.txt
33-
pip install -r requirements.txt
34-
```
35-
36-
#### pipenv
37-
`pipenv` is a Python package manager. Learn more about [pipenv](https://pipenv.pypa.io/en/latest/) and how to install it.
38-
39-
```
40-
# Coming soon
41-
```
42+
This will install all the dependencies of the package including the active branch of `Genie`. We highly recommend that you leverage some form of python version management like [pyenv](https://github.com/pyenv/pyenv) or [anaconda](https://www.anaconda.com/products/individual). Follow [dependencies installation instruction here](./README.md#running-locally)
4243
4344
### Developing
4445
@@ -54,17 +55,17 @@ The GENIE project follows the standard [git flow](https://www.atlassian.com/git/
5455
git pull upstream develop
5556
```
5657
57-
1. Create a feature branch which off the `develop` branch. If there is a GitHub/JIRA issue that you are addressing, name the branch after the issue with some more detail (like `{GH|JIRA}-123-add-some-new-feature`).
58+
1. Create a feature branch which off the `develop` branch. If there is a GitHub/JIRA issue that you are addressing, name the branch after the issue with some more detail (like `{GH|GEN}-123-add-some-new-feature`).
5859
5960
```
6061
git checkout develop
61-
git checkout -b JIRA-123-new-feature
62+
git checkout -b GEN-123-new-feature
6263
```
6364
64-
1. At this point, you have only created the branch locally, you need to push this to your fork on GitHub.
65+
1. At this point, you have only created the branch locally, you need to push this remotely to Github.
6566
6667
```
67-
git push --set-upstream origin JIRA-123-new-feature
68+
git push
6869
```
6970
7071
You should now be able to see the branch on GitHub. Make commits as you deem necessary. It helps to provide useful commit messages - a commit message saying 'Update' is a lot less helpful than saying 'Remove X parameter because it was unused'.
@@ -92,11 +93,8 @@ The GENIE project follows the standard [git flow](https://www.atlassian.com/git/
9293
9394
This package uses [semantic versioning](https://semver.org/) for releasing new versions. The version should be updated on the `develop` branch as changes are reviewed and merged in by a code maintainer. The version for the package is maintained in the [genie/__init__.py](genie/__init__.py) file. A github release should also occur every time `develop` is pushed into `main` and it should match the version for the package.
9495
95-
### Testing
96-
97-
#### Running test pipeline
9896
99-
Make sure to run each of the [pipeline steps here](README.md#developing-locally) on the test pipeline and verify that your pipeline runs as expected. This is __not__ automatically run by Github Actions and have to be manually run.
97+
### Testing
10098
10199
#### Running tests
102100
@@ -110,8 +108,6 @@ Here's how to run the test suite:
110108
pytest -vs tests/
111109
```
112110

113-
Tests in Python are also run automatically by Github Actions on any pull request and are required to pass before merging.
114-
115111
##### Tests in R
116112

117113
This package uses [`testthat`](https://testthat.r-lib.org/) to run tests in R. The test code is located in the [testthat](./R/tests/testthat) subdirectory.
@@ -166,18 +162,6 @@ Follow gitflow best practices as linked above.
166162
12. Push changes in `develop`.
167163
13. Wait for the CI/CD to finish.
168164

169-
### Modifying Docker
170-
171-
Follow this section when modifying the [Dockerfile](https://github.com/Sage-Bionetworks/Genie/blob/main/Dockerfile):
172-
173-
1. Have your synapse authentication token handy
174-
1. ```docker build -f Dockerfile -t <some_docker_image_name> .```
175-
1. ```docker run --rm -it -e SYNAPSE_AUTH_TOKEN=$YOUR_SYNAPSE_TOKEN <some_docker_image_name>```
176-
1. Run [test code](README.md#developing-locally) relevant to the dockerfile changes to make sure changes are present and working
177-
1. Once changes are tested, follow [genie contributing guidelines](#developing) for adding it to the repo
178-
1. Once deployed to main, make sure the CI/CD build successfully completed (our docker image gets automatically deployed via Github Actions CI/CD) [here](https://github.com/Sage-Bionetworks/Genie/actions/workflows/ci.yml)
179-
1. Check that your docker image got successfully deployed [here](https://github.com/Sage-Bionetworks/Genie/pkgs/container/genie)
180-
181165
### Contributing to the docs
182166

183167
This [documentation](https://sagebionetworks.jira.com/wiki/spaces/APGD/pages/3369631808/Contributing+to+Main+GENIE+repository+docs) is internal to Sage employees.

0 commit comments

Comments
 (0)