|
| 1 | +[](https://badge.fury.io/py/octue) |
| 2 | +[](https://travis-ci.com/octue/octue-sdk-python) |
| 3 | +[](undefined) |
| 4 | +[](https://octue.readthedocs.io/en/latest/?badge=latest) |
| 5 | +[](https://github.com/pre-commit/pre-commit) |
| 6 | +[](https://github.com/ambv/black) |
| 7 | +[](https://www.blackgirlscode.com/) |
| 8 | + |
1 | 9 | # octue-sdk-python <span><img src="http://slurmed.com/fanart/javier/213_purple-fruit-snake.gif" alt="Purple Fruit Snake" width="100"/></span> |
2 | | -SDK for python based apps running within octue. |
| 10 | + |
| 11 | +Utilities for running python based data services, digital twins and applications with the Octue toolkit and [twined](https://www.twined.readthedocs.io) SDK for python based apps running within octue. |
| 12 | + |
| 13 | +[See documentation.](https://octue.readthedocs.io/en/latest) |
| 14 | + |
| 15 | + |
| 16 | +## Developer notes |
| 17 | + |
| 18 | +**Documentation for use of the library is [here](https://{{library_name}}.readthedocs.io). You don't need to pay attention to the following unless you plan to develop {{library_name}} itself.** |
| 19 | + |
| 20 | +### Getting started |
| 21 | + |
| 22 | +1. Click 'use this template' to the top right, and away you go. |
| 23 | +2. Search for `{{` in your new repository. Do search and replace for the various terms - it's obvious what they are, like replace `{{github_username}}` with your github username! |
| 24 | +3. Set up the license you need in `LICENSE`. |
| 25 | +4. If you need to deploy to pypi, you have to do the first deploy manually - travis can't do that for you. [See the packaging instructions](https://packaging.python.org/tutorials/distributing-packages/#uploading-your-project-to-pypi). |
| 26 | + |
| 27 | +### Pre-Commit |
| 28 | + |
| 29 | +You need to install pre-commit to get the hooks working. Do: |
| 30 | +``` |
| 31 | +pip install pre-commit |
| 32 | +pre-commit install |
| 33 | +``` |
| 34 | + |
| 35 | +Once that's done, each time you make a commit, the following checks are made: |
| 36 | + |
| 37 | +- valid github repo and files |
| 38 | +- code style |
| 39 | +- import order |
| 40 | +- PEP8 compliance |
| 41 | +- documentation build |
| 42 | +- branch naming convention |
| 43 | + |
| 44 | +Upon failure, the commit will halt. **Re-running the commit will automatically fix most issues** except: |
| 45 | + |
| 46 | +- The flake8 checks... hopefully over time Black (which fixes most things automatically already) will negate need for it. |
| 47 | +- You'll have to fix documentation yourself prior to a successful commit (there's no auto fix for that!!). |
| 48 | + |
| 49 | +You can run pre-commit hooks without making a commit, too, like: |
| 50 | +``` |
| 51 | +pre-commit run black --all-files |
| 52 | +``` |
| 53 | +or |
| 54 | +``` |
| 55 | +# -v gives verbose output, useful for figuring out why docs won't build |
| 56 | +pre-commit run build-docs -v |
| 57 | +``` |
| 58 | + |
| 59 | + |
| 60 | +### Contributing |
| 61 | + |
| 62 | +- Please raise an issue on the board (or add your $0.02 to an existing issue) so the maintainers know |
| 63 | +what's happening and can advise / steer you. |
| 64 | + |
| 65 | +- Create a fork of octue-sdk-python, undertake your changes on a new branch, (see `.pre-commit-config.yaml` for branch naming conventions). To run tests and make commits, |
| 66 | +you'll need to do something like: |
| 67 | +``` |
| 68 | +git clone <your_forked_repo_address> # Fetches the repo to your local machine |
| 69 | +cd octue-sdk-python # Move into the repo directory |
| 70 | +pyenv virtualenv 3.6.9 myenv # Makes a virtual environment for you to install the dev tools into. Use any python >= 3.6 |
| 71 | +pyend activate myenv # Activates the virtual environment so you don't screw up other installations |
| 72 | +pip install -r requirements-dev.txt # Installs the testing and code formatting utilities |
| 73 | +pre-commit install # Installs the pre-commit code formatting hooks in the git repo |
| 74 | +tox # Runs the tests with coverage. NB you can also just set up pycharm or vscode to run these. |
| 75 | +``` |
| 76 | + |
| 77 | +- Adopt a Test Driven Development approach to implementing new features or fixing bugs. |
| 78 | + |
| 79 | +- Ask the maintainers *where* to make your pull request. We'll create a version branch, according to the |
| 80 | +roadmap, into which you can make your PR. We'll help review the changes and improve the PR. |
| 81 | + |
| 82 | +- Once checks have passed, test coverage of the new code is 100%, documentation is updated and the Review is passed, we'll merge into the version branch. |
| 83 | + |
| 84 | +- Once all the roadmapped features for that version are done, we'll release. |
| 85 | + |
| 86 | + |
| 87 | +### Release process |
| 88 | + |
| 89 | +The process for creating a new release is as follows: |
| 90 | + |
| 91 | +1. Check out a branch for the next version, called `vX.Y.Z` |
| 92 | +2. Create a Pull Request into the `master` branch. |
| 93 | +3. Undertake your changes, committing and pushing to branch `vX.Y.Z` |
| 94 | +4. Ensure that documentation is updated to match changes, and increment the changelog. **Pull requests which do not update documentation will be refused.** |
| 95 | +5. Ensure that test coverage is sufficient. **Pull requests that decrease test coverage will be refused.** |
| 96 | +6. Ensure code meets style guidelines (pre-commit scripts and flake8 tests will fail otherwise) |
| 97 | +7. Address Review Comments on the PR |
| 98 | +8. Ensure the version in `setup.py` is correct and matches the branch version. |
| 99 | +9. Merge to master. Successful test, doc build, flake8 and a new version number will automatically create the release on pypi. |
| 100 | +10. Go to code > releases and create a new release on GitHub at the same SHA. |
| 101 | + |
| 102 | + |
| 103 | +## Documents |
| 104 | + |
| 105 | +### Building documents automatically |
| 106 | + |
| 107 | +The documentation will build automatically in a pre-configured environment when you make a commit. |
| 108 | + |
| 109 | +In fact, the way pre-commit works, you won't be allowed to make the commit unless the documentation builds, |
| 110 | +this way we avoid getting broken documentation pushed to the main repository on any commit sha, so we can rely on |
| 111 | +builds working. |
| 112 | + |
| 113 | + |
| 114 | +### Building documents manually |
| 115 | + |
| 116 | +**If you did need to build the documentation** |
| 117 | + |
| 118 | +Install `doxgen`. On a mac, that's `brew install doxygen`; other systems may differ. |
| 119 | + |
| 120 | +Install sphinx and other requirements for building the docs: |
| 121 | +``` |
| 122 | +pip install -r docs/requirements.txt |
| 123 | +``` |
| 124 | + |
| 125 | +Run the build process: |
| 126 | +``` |
| 127 | +sphinx-build -b html docs/source docs/build |
| 128 | +``` |
| 129 | + |
| 130 | +Tom Clark, founder of octue |
| 131 | +We've been developing open-source tools to make |
| 132 | +it easy for normal, mortal scientists and |
| 133 | +engineers to easily create, use and connect |
0 commit comments