rahix/openflexure-microscope-server
1
0
Fork 0
Code Issues Pull requests Projects Releases Packages Wiki Activity Actions

Updated readme and version-bump for clarity

Browse source
This commit is contained in:
Richard Bowman 2021-03-31 10:21:45 +01:00
parent 1cea75be70
commit 9783dfaeff
2 changed files with 15 additions and 14 deletions
Download patch file Download diff file Expand all files Collapse all files

27
README.md
View file

@ -31,10 +31,9 @@ There are 2 important settings files:
## Creating releases
* Update the applications internal version number
* `poetry version X.y.z` (replace X.y.z with a semantic version number)
* or `poetry version {patch/minor/major}` (see https://python-poetry.org/docs/cli/#version)
* Edit ``setup.py`` to update the version number
* Git commit and git push
* Create a new version tag on GitLab (e.g. V2.6.11)
* Create a new version tag on GitLab (e.g. ``v2.6.11``)
* Make sure you prefix a lower case 'v', otherwise it won't be recognised as a release!
* This tagging will trigger a CI pipeline that builds the JS client, tarballs up the server, and deploys it
* Note: This also updates the build server's nginx redirect map file
@ -56,10 +55,10 @@ The Raspberry Pi image we use currently ships with Python 3.7.3. For local devel
* `python -m venv .venv`
* `source .venv/bin/activate` (on Linux) or `.venv/Scripts/activate` (on Windows)
* `pip install pipenv`
* `pipenv install`
* `pipenv install --dev` (This will install development dependencies. If you don't need these, `pipenv install` will get you just the dependencies needed to run the server, which takes about half the time.)
* Finally, run the server:
* You can use `ofm serve` or `ofm restart` on the Raspberry Pi to manage the server.
* To run the server locally, with dummy hardware, you can use ``poetry run python -m openflexure_microscope.api.app`` to start a development-mode Flask server on ``localhost:5000``
* To run the server locally, with dummy hardware, you can use ``python -m openflexure_microscope.api.app`` to start a development-mode Flask server on ``localhost:5000``
### Set up the Javascript environment and build
* The Flask web application, written in Python, serves a web application written in ``Vue.js``. This is distributed as part of the built version of the server, hosted on our [build server](https://build.openflexure.org/openflexure-microscope-server/).
@ -77,12 +76,13 @@ The Raspberry Pi image we use currently ships with Python 3.7.3. For local devel
* You access the development server on a different port (it's printed on the command line when you run the above command). This means that when it starts up you will need to tell it where the microscope server is, using the "override API origin" field in the page that pops up. If you are running a test server on your computer, this is most likely ``http://localhost:5000/``.
## Formatting, linting, and tests
All of the commands below assume that you are running in the OFM virtual environment, i.e. you have run ``ofm activate`` on an OpenFlexure SD card, or ``source .venv/bin/activate`` on Linux, or ``.venv/Scripts/activate``on Windows.
### Tl;dr
**Before committing**
* To auto-format the Python code run `poetry run poe format`
* To auto-format the Python code run `poe format`
* To auto-format the Javascript code, run
* ``cd openflexure_microscope/api/static``
* ``npm run lint``
@ -91,7 +91,7 @@ Auto-formats the code
**Before submitting a merge request/merging**
* To auto-format and type-check the Python code run `poetry run poe check`
* To auto-format and type-check the Python code run `poe check`
* To auto-format the Javascript code, run
* ``cd openflexure_microscope/api/static``
* ``npm run lint``
@ -107,28 +107,29 @@ Our CI will check each of these automatically, so ensuring they pass locally wil
* **Black** - Code formatting with minimal configuration.
* While sometimes it's not perfect, its fine 90% of the time and prevents arguments about formatting.
* Automatically formats your code
* `poetry run poe black`
* This will rewrite your files in-place, so if you want to be able to revert, make a backup first!
* `poe black`
* **Pylint** - Static code analysis
* Analyses your code, failing if issues are detected.
* We've disabled some less severe warnings, so _if anything fails your merge request will be blocked_
* `poetry run poe pylint`
* `poe pylint`
* **Mypy** - Type checking
* Analyses your type hints and annotations to flag up potential bugs
* Where possible, use type hints in your code. Even if dependencies don't support it, it'll help identify issues.
* `poetry run poe mypy`
* `poe mypy`
* **Pytest** - Unit testing
* While unit testing is of limited use due to our dependence on real hardware, some simple isolated functions can (and should) be unit tested.
* `poetry run poe test`
* `poe test`
Though not in the CI, our `format` script also runs isort:
* **Isort** - Import sorting
* Automatically organises your imports to stop things getting out of hand
* `poetry run poe isort`
* `poe isort`
## Build-system
As of 1.0.0b0, we're using [Poetry](https://github.com/sdispater/poetry) to manage dependencies, build, and distribute the package. All package information and dependencies are found in `pyproject.toml`, in line with [PEP 518](https://www.python.org/dev/peps/pep-0518/). If you're developing this package, make use of `poetry.lock` to ensure you're using the latest locked dependency list.
As of ``2.10.0b0`` we have switched to using ``pipenv`` for managing dependencies, and a standard ``setuptools`` based build system. See "local installation" above for instructions on how to install the project.
## Changelog generation