Commit
This commit does not belong to any branch on this repository, and may belong to a fork outside of the repository.
* add dev docs (draft) * update instructions, add news * pre-commit * add development to toc
- Loading branch information
Showing
3 changed files
with
100 additions
and
0 deletions.
There are no files selected for viewing
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Original file line number | Diff line number | Diff line change |
---|---|---|
@@ -0,0 +1,80 @@ | ||
# Development | ||
|
||
## Local development setup | ||
|
||
`menuinst` is a multiplatform tool with heavy reliance on OS-specific behaviour, APIs and tools. | ||
Each platform requires its own setup. | ||
|
||
> Since some tests might leave traces behind, we recommend running the tests from a VM (if you can). | ||
For your own protection, some tests only run when the `CI` env var has been set to a non-empty value. If you do want to run these on your local machine, you can set the `CI` env var to `1` before running the tests; it better be on a VM though! | ||
|
||
## Linux | ||
|
||
We recommend using Docker to run the tests on Linux. However, some tasks require a graphical environment. | ||
|
||
### Docker setup | ||
|
||
1. We can leverage `conda/conda`'s conda-forge-based CI image for this. Make sure to mount the `menuinst` source to a known location in the container. In the example below, we are using `~/my/repos/menuinst`, mapped to `/opt/menuinst-src`. | ||
|
||
``` | ||
$ docker run -it --rm --platform=linux/aarch64 \ | ||
-v ~/my/repos/menuinst:/opt/menuinst-src \ | ||
ghcr.io/conda/conda-ci:main-linux-python3.10-conda-forge bash | ||
``` | ||
|
||
2. Create a new conda environment and install the dependencies: | ||
|
||
``` | ||
$ conda create -n menuinst-dev \ | ||
conda-canary/label/conda-conda-pr-11882::conda \ | ||
pip \ | ||
pytest \ | ||
pytest-cov \ | ||
pydantic \ | ||
hypothesis \ | ||
hypothesis-jsonschema | ||
``` | ||
|
||
3. Activate the environment and install `menuinst`: | ||
|
||
``` | ||
$ conda activate menuinst-dev | ||
$ python -m pip install -vv /opt/menuinst-src | ||
``` | ||
|
||
4. Run the tests: | ||
|
||
``` | ||
$ cd /opt/menuinst-src | ||
$ pytest | ||
``` | ||
|
||
### VM setup | ||
|
||
## macOS | ||
|
||
Some of the tests involve modifying the system's menu. While we have added some teardown logic to | ||
undo the modifications once done, it might still leave some artifacts behind. We recommend running | ||
the tests from a VM (if you can). | ||
|
||
### VM setup with UTM | ||
|
||
This is recommended for Apple Silicon. | ||
|
||
1. Download [UTM](https://mac.getutm.app/) and create a new VM for macOS using the default | ||
settings. The UI only requires a couple clicks, but the download and automated install will take a few hours, so be patient. | ||
|
||
### Debug in CI | ||
|
||
In extreme cases, you can edit the Github Actions workflow to add a step for [`mxschmitt/action-tmate`](https://github.com/marketplace/actions/debugging-with-tmate) and then connect to the VM via SSH. Please be mindful of the resources and only add it for the platforms and Python versions you need. For example: | ||
|
||
```yaml | ||
- name: Setup tmate session | ||
uses: mxschmitt/action-tmate@v3 | ||
timeout-minutes: 60 | ||
if: ${{ failure() && matrix.os == 'macos-latest' && matrix.python-version == '3.9' }} | ||
``` | ||
|
||
## Windows | ||
|
||
Some tests will add changes to your system configuration (Windows registry, new files added, etc). We try to clean up after ourselves, but it's not always possible. We recommend running the tests from a VM (if you can). |
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Original file line number | Diff line number | Diff line change |
---|---|---|
|
@@ -11,4 +11,5 @@ getting-started | |
defining-shortcuts | ||
conda | ||
reference | ||
development | ||
``` |
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Original file line number | Diff line number | Diff line change |
---|---|---|
@@ -0,0 +1,19 @@ | ||
### Enhancements | ||
|
||
* <news item> | ||
|
||
### Bug fixes | ||
|
||
* <news item> | ||
|
||
### Deprecations | ||
|
||
* <news item> | ||
|
||
### Docs | ||
|
||
* Add development documentation. (#131) | ||
|
||
### Other | ||
|
||
* <news item> |