-
Notifications
You must be signed in to change notification settings - Fork 44
2. Developer Guide
This page describes what you need to know for developing this package.
We vaguely follow the git-flow workflow. The link provided explains it very well, but to summarize: the develop branch is the main branch that all new features get added to. The main branch holds the code we want most users to be using. When we wish to release a new version, we simply merge the state of develop into main, propagating all of the changes at once. We will describe this process in more detail below.
When developing new features, we ask that you create a branch off of develop and do your work there. When the feature is ready to merge in, we prefer git rebase to git merge. This creates a cleaner, linear history. You can read about why we do it and what a rebase is at this link.
The following steps show how to develop a new feature.
git checkout develop
git checkout -b feature
- develop your feature
- commit changes, repeat process until satisfied
git rebase -i develop
- squash, edit, commits
- submit PR on github.
Note: the following are for repository admins only, if you've submitted a PR, one of us will review and either ask for changes or merge the code in.
- when ready, rebase and merge feature into develop
git checkout develop
git pull -or- git reset --hard origin/develop
And the following steps show how to perform a release.
git checkout main
git merge develop
git tag x.x.x
git push origin x.x.x
Here we will discuss how tests are defined and run in Tidy3d.
The tests live in tests/ directory.
We use pytest package for our testing.
To run all of the tests, call:
pytest -rA tests
This code will trigger pytest to through each file in tests/ called test*.py and run each function in that file with a name starting with test.
If all of these functions run without any exceptions being raised, the tests pass!
The specific configuration we use for pytest lives in pytest.ini.
These tests are automatically run when code is submitted using Github Actions, which tests on python 3.7, 3.8, 3.9 running on Ubuntu, MacOS, and Windows operating systems, as well as Flexcompute's servers.
Note: The -rA flag is optional but produces output that is easily readable.
Note: You may notice warnings and errors in the pytest output, this is because many of the tests intentionally trigger these warnings and errors to ensure they occur in certain situations. The important information about the success of the test is printed out at the bottom of the pytest output for each file.
To maintain code neatness, we use black package for code formatting and pylint to find where the code deviates from standard practices as outlined in the PEP8 style format.
To run black and format all python files:
black .
To run pylint and check for deviations from PEP8.
python lint.py
The configuration defining what pylint will catch lives in .pylintrc.
When submitting code, for review, pylint must give no warnings and black should be run.
We use tox to run the tests for different python distributions, to run tox, simply call
tox
The configuration lives in tox.ini.
We use GitHub Actions to perform these tests automatically and across different operating systems.
On commits, each of the pytest tests are run using python 3.7, 3.8, 3.9 installed on Ubuntu, MacOS, and Windows operating systems, as well as Flexcompute's servers.
See the "actions" tab for details on previous tests and .github/workflows/run_tests.yml for the confuration and to see the specific tests run.
See this for more explanation.
There are additional tests in both the documentation and our private backend code. The same practices outlined here apply to those tests.
A useful explanation for those curious to learn more about the reasoning behind these decisions.
https://www.youtube.com/watch?v=DhUpxWjOhME
If you have any questions at all and want to do something, but are not sure if it's correct, create an issue or reach out to @tylerflex or @momchilflex.
Visit the Tidy3D documentation for more details.