Development Guide 🛠️

Development Guide 🛠️#

Welecome to the tidy3d developers guide!

An Introduction to the Development Flow#

This page hopefully will get you started to develop Tidy3D.

TLDR:

  • Branch off of the target branch (usually develop or pre/x.x), work on your branch, and submit a PR when ready.

  • Use isolated development environments with poetry.

  • Use ruff to lint and format code, and install the pre-commit hook via pre-commit install to automate this.

  • Document code using NumPy-style docstrings.

  • Write unit tests for new features and try to maintain high test coverage.

Understanding Virtual Environments#

Introduction#

In larger projects, it’s crucial to have a separate Python environment for each feature or branch you work on. This practice ensures isolation and reproducibility, simplifying testing and debugging by allowing issues to be traced back to specific environments. It also facilitates smoother integration and deployment processes, ensuring controlled and consistent development. Managing multiple environments might seem daunting, but it’s straightforward with the right tools. Follow the steps below to set up and manage your environments efficiently.

Benefits#

  • Isolation: Avoids conflicts between dependencies of different features.

  • Reproducibility: Each environment can be easily replicated.

  • Simplified Testing: Issues are contained within their respective environments.

  • Smooth Integration: Ensures features are developed in a consistent setting.

Prerequisites#

Make sure that you have poetry installed. This can be done system-wide with pipx or within a conda environment. Note that we use conda only for setting up the interpreter (Python version) and poetry, not for managing dependencies. Refer to the official development guide for detailed instructions:

https://docs.flexcompute.com/projects/tidy3d/en/stable/development/index.html#installation

Setting Up a New Environment#

  1. Check out the branch:

    git checkout branch

  2. Set up the environment with conda (skip this step if you don’t use conda):

    conda create -n branch_env python=3.11 poetry
conda activate branch_env
poetry env use system
poetry env info # verify you're running the right environment now

  3. Install dependencies with poetry:

    poetry install -E dev
poetry run pre-commit install

  4. Update the environment when switching to a different branch:

    poetry install -E dev

Multiple Folders or Worktrees#

If you have multiple folders (e.g., multiple clones or git worktrees), you will need to repeat the environment setup for each folder. Ensure that each folder has its own isolated environment.

By following these steps, you can maintain isolated and reproducible environments for each branch and feature, leading to a more efficient and error-free development process.

Using poetry for package management#

What is Poetry#

Poetry is a package management tool for Python.

Among other things, it provides a nice way to:

  • Manage dependencies

  • Publish packages

  • Set up and use virtual environments

Effectively, it is a command line utility (similar to pip) that is a bit more convenient and allows more customization.

Why do we want to use it#

  1. To improve our dependency management, which is used to be all over the place. We have several requirements.txt files that get imported into setup.py and parsed depending on the extra arguments passed to pip install. Poetry handles this much more elegantly through a pyproject.toml file that defines the dependency configuration very explicitly in a simple data format.

  2. Reproducible development virtual environments means that everyone is using the exact same dependencies, without conflicts. This also improves our packaging and release flow.

How to install it?#

We provide custom installation instructions and an installation script on TODO ADD LINK SECTION. However, you can read more information here: see the poetry documentation for a guide to installation and basic use.

Usage Examples#

To add poetry to a project#

To initialize a new basic project with poetry configured, run:

poetry new poetry-demo

To add poetry to an existing project, cd to the project directory and run:

poetry init

Configuring dependencies#

The dependency configuration is in the editable file called pyproject.toml. Here you can specify whatever dependencies you want in your project, their versions, and even different levels of dependencies (e.g., dev).

To add a dependency to the project (e.g., numpy), run:

poetry add numpy

You can then verify that it was added to the tool.poetry.dependencies section of pyproject.toml.

For many more options on defining dependencies, see here.

Virtual environments#

Now that the project has had poetry configured and the correct dependencies are specified, we can use poetry to run our scripts/shell commands from a virtual environment without much effort. There are a few ways to do this:

Poetry run: One way is to precede any shell command you’d normally run with poetry run. For example, if you want to run python tidy_script.py from the virtual environment set up by poetry, you’d do:

poetry run python tidy3d_script.py

Poetry shell:

If you want to open up a shell session with the environment activated, you can run:

poetry shell

And then run your commands. To return to the original shell, run exit.

There are many more advanced options explained here.

Publishing Package#

To upload the package to PyPI:

poetry build

poetry publish

Note that some configuration must be set up before this would work properly.

Code Quality Principles#

When writing a code snippet, remember the saying: “code is read more than written”. We want to maintain our code maintainable, readable and high quality.

Linting & Formatting#

To maintain code quality, we use Ruff as a linter and code formatter. A linter analyzes code to identify and flag potential errors, stylistic issues, and code that doesn’t adhere to defined standards (such as PEP8). A code formatter automatically restructures the code to ensure it is consistently styled and properly formatted, making it consistent across the code base.

Run ruff format to format all Python files:

poetry run ruff format .

Run ruff check to check for style and other issues. Many common warnings can be automatically fixed with the --fix flag:

poetry run ruff check tidy3d --fix

The configuration defining what ruff will correct lives in pyproject.toml under the [tool.ruff] section.

When submitting code, for tests to pass, ruff should give no warnings.

Documentation#

Document all code you write using NumPy-style docstrings.

Testing#

Here we will discuss how tests are defined and run in Tidy3d.

Unit Testing#

The tests live in tests/ directory.

We use pytest package for our testing.

To run all of the tests, call:

poetry run pytest -rA tests

This command will trigger pytest to go 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 the [tool.pytest.ini_options] section of pyproject.toml.

These tests are automatically run when code is submitted using GitHub Actions, which tests on Python 3.9 through 3.12 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 get a code coverage report:

pip install pytest-cov

if not already installed

To run coverage tests with results printed to STDOUT:

pytest tests --cov-report term-missing --cov=tidy3d

To run coverage tests and get output as .html (more intuitive):

pytest tests --cov-report=html --cov=tidy3d
open htmlcov/index.html

Automated Testing#

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.9 - 3.12 installed on Ubuntu, MacOS, and Windows operating systems.

See the “actions” tab for details on previous tests and .github/workflows/run_tests.yml for the configuration and to see the specific tests run.

See this for more explanation.

Other Tests#

There are additional tests in both the documentation and our private backend code. The same practices outlined here apply to those tests.

More Resources on Testing#

A useful explanation for those curious to learn more about the reasoning behind these decisions:

https://www.youtube.com/watch?v=DhUpxWjOhME <https://www.youtube.com/watch?v=DhUpxWjOhME>

tidy3d Project Structure#

As of tidy3d>=2.6, the frontend has been restructured to improve the development cycle. The project directories follow the following structure, which is derived from some recommended Python project architecture guides. This is a handy structure because many tools, such as sphinx, integrate quite well with this type of project layout.

docs/
    # sphinx rst files
    ...
    notebooks/
        # Git submodule repository
        # Checks out github.com/flexcompute/tidy3d-notebooks
    faq/
        # Git submodule repository
        # Checks out github.com/flexcompute/tidy3d-faq
tests/
    # pytest source and docs
    # pytest notebooks
scripts/
    # useful handy scripts
tidy3d/
    # python source code
...
pyproject.toml # python packaging
poetry.lock # environment management

It is important to note the new tools we are using to manage our development environment and workflow.

  • poetry

  • pipx

Important Branches#

We currently have three main branches that have to be kept track of when creating a release, each with different functionality.

Project Branches#

Name

Description

Caveats

latest

Contains the latest version of the docs. Version release tags are created from this branch.

Feature PRs should not be made to this branch as will cause divergence. Only in important documentation patches.

develop

Contains the “staging” version of the project. Patch versions and development occurs from these branches.

Docs PRs that are non-crucial for the current version should be made to this branch.

pre/^*

Contains the next version of the project.

Documentation and source code that will only go live in the next version should be updated here.

Sometimes, hopefully infrequently, the latest and develop branches might diverge. It is important to bring them back together. However, what happens if we rebase develop into latest?

It could be argued that all the commits in the latest branch should have constructed within the develop branch. Then, there is the question if we want to maintain the commit history accordingly. If we just want to maintain the content, then rebasing and fixing up all the branches works fine. The problem with a merge commit is that it inserts the commits at the historical period in which they were made, rather than the commit period in which we desire to add them. Hence, it makes sense to merge the develop and latest branches in order to maintain the same history, assuming the commits should in theory have been in both branches.

Development Environment Installation#

The Fast Lane#

Maybe you already have tidy3d installed in some form. After installing version tidy3d>=2.6, you can use a few terminal commands to set you up on the correct environment and perform common development tasks. Just run in your terminal, tidy3d develop to get the latest list of commands.

It does not matter how you have installed tidy3d before as long as you have any form of tidy3d>=2.6 in your environment. This can help you transition from a standard user installation to a development environment installation.

Quick Start#

Instructions for anyone who wants to migrate to the development flow from a version before 2.6:

For ubuntu:

git clone https://github.com/flexcompute/tidy3d.git
cd tidy3d
# Make sure you're in a branch > pre/2.6 and you can `import tidy3d` in python
pip install -e . # or whatever local installation works for you
tidy3d develop # Read all the new development helper commands
# tidy3d develop uninstall-dev-envrionment # in case you need to reset your environment
tidy3d develop install-dev-environment # install all requirements that you don't have and verify the exisiting ones
poetry run tidy3d develop verify-dev-environment # reproducibly verify development envrionment
# poetry run tidy3d develop build-docs # eg. reproducibly build documentation

Now you can run the following tidy3d cli commands to test them.

Automatic Environment Installation Beta#

If you are transitioning from the old development flow, to this new one, there are a list of commands you can run to make your life easier and set you up well:

# Automatically check and install requirements like pipx, poetry, pandoc
tidy3d develop install-dev-environment

Note that this is just a automatic script implementation of the The Detailed Lane instructions. It is intended to help you and raise warnings with suggestions of how to fix an environment setup issue. You do not have to use this helper function and can just follow the instructions in The Detailed Lane. All commands are echo-ed in the terminal so you will be able to observe and reproduce what is failing if you desire.

The way this command works is dependent on the operating system you are running. There are some prerequisites for each platform, but the command line tool will help you identify and install the tools it requires. You should rerun the command after you have installed any prerequisite as it will just progress with the rest of the tools installation. If you already have the tool installed, it will verify that it conforms to the supported versions.

This command will first check if you already have installed the development requirements, and if not, it will run the installation scripts for pipx, poetry, and ask you to install the required version of pandoc. It will also install the development requirements and tidy3d package in a specific poetry environment.

Environment Verification#

If you rather install poetry, pipx and pandoc yourself, you can run the following command to verify that your environment conforms to the reproducible development environment which would be equivalent to the one installed automatically above and described in The Detailed Lane.

tidy3d develop verify-dev-environment

The Detailed Lane#

If you do not have any of the above tools already installed and want to install them manually, let’s go through the process of setting things up from scratch:

Environment Requirements#

Make sure you have installed pipx. We provide common installation flows below:

This installation flow requires a python3 installation. Depending how you have installed python3, you may have to edit this command to run on your target installation. Further instructions by pipx here

python3 -m pip install --user pipx
python3 -m pipx ensurepath

Then install poetry:

Further instructions in the poetry installation instructions

python3 -m pipx install poetry

After restarting the bash terminal, you should be able to find poetry in your PATH if it has been installed correctly:

poetry --version
poetry # prints all commands

If you want to locally build documentation, then it is required to install pandoc<3.

Further instructions in the pandoc installation instructions. Note you will need permissions to do this.

sudo apt-get update
sudo apt-get install pandoc

Now you need to install the package in the reproducible poetry environment in development mode:

poetry install -E dev

Congratulations! Now you have all the required tools installed, you can now use all the poetry run tidy3d develop commands reproducibly.

If you want to contribute to the project, read the following section:

More Contribution Requirements#

If you want to contribute to the development of tidy3d, you can follow the instructions below to set up your development environment. This will allow you to run the tests, build the documentation, and run the examples. Another thing you need to do before committing to the project is to install the pre-commit hooks. This will ensure that your code is formatted correctly and passes the tests before you commit it. To do this, run the following command:

poetry run pre-commit install

This will run a few file checks on your code before you commit it. After this whenever you commit, the pre-commit hooks will run automatically. If any of the checks fail, you will have to fix the issues before you can commit. If for some reason, it’s a check you want to waive, you can follow the instructions of the tool to automatically waive them or you can run the following command to skip the checks only on minimal circumstances:

git commit --no-verify

You can also run the checks manually on all files by running the following command:

poetry run pre-commit run --all-files

Packaging Equivalent Functionality#

This package installation process should be approximately equivalent to the previous setup.py installation flow. Independent of the poetry development flow, it is possible to run any of the following commands in any particular virtual environment you have configured:

pip install tidy3d[dev]
pip install tidy3d[docs]
pip install tidy3d[web]
...
pip install tidy3d[jax]

All these options can be found inside the pyproject.toml tool.poetry.extras section. Each has a corresponding list of dependencies whose versions are defined on the tool.poetry.dependencies section of the file.

Using the Development Flow#

Developing tidy3d with poetry#

poetry is an incredibly powerful tool for reproducible package development environments and dependency management.

If you are developing tidy3d, we recommend you work within the configured poetry environment defined by poetry.lock. The way to install this environment is simple:

cd tidy3d/
poetry install -E dev

This function will install the package with all the development dependencies automatically. This means you should be able to run any functionality that is possible with tidy3d reproducibly.

It is important to note the function above is equivalent to pip install tidy3d[dev], but by using poetry there is a guarantee of using the reproducible locked environment.

poetry with an external virtual environment#

It is recommended to use poetry for package development. However, there are some cases where you might need to use an external virtual environment for some operations. There are a few workarounds where you can leverage the reproducibility of the poetry managed environment with the freedom of a standard virtual environment. There are a few more instructions and explanations in the poetry env docs . F See the following example:

mamba create -n tidy3denv python==3.10 # create venv with mamba
mamba activate tidy3denv # activate the venv
poetry env use python # using the mamba venv python now
poetry env info # verify the venvs used by poetry and mamba
cd anywhere
# you can use the python activated venv anywhere.

There are also other methodologies of implementing common dependencies management.

Common Utilities#

There are a range of handy development functions that you might want to use to streamline your development experience.

Use Cases#

Description

Caveats

Command

Benchmark timing import of tidy3d

Verify the available timing tests by running the command without any arguments.

poetry run tidy3d develop benchmark-timing-operations -c <timing_command>

Build documentation on reproducible environment

poetry run tidy3d develop build-docs

Build documentation with latest remote notebooks

It is defaulted to the develop branch of the tidy3d-notebooks repository.

poetry run tidy3d develop build-docs-remote-notebooks

Complete notebooks + base testing of the tidy3d

Make sure you have the notebooks downloaded.

poetry run tidy3d develop test-all

Dual snapshot between the tidy3d and notebooks source and submodule repository.

Make sure you are on the correct git branches you wish to commit to on both repositories, and all non-git-ignored files will be added to the commit.

tidy3d develop commit <your message>

Interactively convert all markdown files to rst (replacement for m2r2)

poetry run tidy3d develop convert-all-markdown-to-rst

Running pytest commands inside the poetry environment.

Make sure you have already installed tidy3d in poetry and you are in the root directory.

poetry run pytest

Run coverage testing from the poetry environment.

poetry run coverage run -m pytest

Standard testing of the tidy3d frontend

Make sure you have already installed tidy3d in poetry and you are in the root directory.

poetry run tidy3d develop test-base

Using tidy3d develop commands inside the poetry environment.

Make sure you have already installed tidy3d in poetry

poetry run tidy3d develop <your command>

Update lockfile after updating a dependency in pyproject.toml

Remember to install after this command.

poetry lock

Update and replace all the docstrings in the codebase between versions

poetry run tidy3d develop replace-in-files

Recommendations#

Standardised Commit Messages#

Now, realistically, this is a matter of preference. However, it could be argued there is something nice in having standard commit messages that can be easily searched through to understand the role of each change, and also render nicely in the git history. Also, having a commit standard maybe makes people looking through our code feel that we take pride in our work and also like to make it nice. It is debatable whether this is a way to do this, however, we can update these recommendations depending on how we consider best.

However, if we do decide to commit with emojis, I believe it would be worth having a standard, so that it does not get polluted with different emojis (as I have been guilty of before) and also as can be seen in other open-source projects.

Commit Standard#

Purpose

Emoji

Types

Example

✨ New Feature

:sparkles:

FEAT:

:sparkles: FEAT: <my commit message>

🔧 Fix Broken Code

:wrench:

FIX:

:wrench: FIX: <my commit message>

📦 Packaging-related

:package:

BUILD:

:package: BUILD: <my commit message>

📖 Documentation-related

:book:

DOCS:

:book: DOCS: <my commit message>

🚀 Refactor code

:rocket:

REFC:

:rocket: REFC: <my commit message>

🧪 Testing related

:test_tube:

TEST:

:test_tube: TEST: <my commit message>

🎉 Release commit

:tada:

RELEASE:

:tada: RELEASE: <my commit message>

Package Speedup Best Practices#

tidy3d is a pretty big project already, and will get bigger. We want to optimise the performance of the codebase throughout the multiple operations that we perform.

We want to improve the speed of the project import and there are a few techniques to do this which are inherent to the way we write our code.

We have already begun facing these type of code-speed issues as first raised here, here

So when we import dependencies inside our code-base in particular where these are used, we will try to do the following:

from mypackage import just_what_I_need

instead of

import mypackage

This is because the latter will import the entire package, which is not necessary and will slow down the code.

Managing Optional Dependencies On-The-Fly#

If you look within pyproject.toml, it is possible to see that we have different packages relating to different functionalities that are optional.

Some examples from these are [vtk, jax, trimesh, gdstk, gdspy] etc. What we want to do is improve the import speed of the core-package in order to minimise small core operations. As we scale into a bigger package, decoupling these type of imports from the total pacakge import is essential.

Benchmarking Package Import#

We want to make the tidy3d package be as light as possible for a given set of operations. As such, it is important to understand exactly where a given set of operations is expending computational power.

We have a set of utilties to verify this.

poetry run tidy3d develop benchmark-timing-operations

Release Flow#

This page contains all the relevant information relating to each version release process for tidy3d.

Feature Contribution#

Feature Development Workflow#

1. Create a branch off of develop#

Our pre/x.x branches are where new features, bug fixes, and other things get added before a major release. To switch to the pre/x.x branch:

git checkout pre/x.x

And then you can create a new branch from here with your GitHub username pre-pended:

git checkout -b myusername/cool-feature

Currently most of our release development flow is made under the latest pre/* branch under the main frontend tidy3d repository. You want to fork from this latest branch to develop your feature in order for it to be included under that release.

We are using a variation of the gitflow workflow - so this is the first thing to familiarize yourselves with. The link provided explains it very well, but to summarize: features get added to a pre-release branch (pre/x.x), and once all the features for a particular release have been implemented, the pre-release branch gets merged into develop. The latest 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 latest, 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 whichever branch you aim to contribute to. This is typically either the current pre-release branch named pre/x.x or develop depending on what stage of development we are currently in. You then work on your branch, and 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. And see Momchil’s more specific notes here.

Most importantly, all contributions should happen through a PR from a feature branch into the develop branch.

The extra step that we have in our workflow is to always rebase and merge instead of simply merge branches. This has the advantage of avoiding a mess of crossing paths and keeps the history clean, but it does require a little more work. As an extra advantage, once you get the hang of rebasing it also becomes a very useful tool to prune your commits and write more meaningful commit messages when you’re done with the work. The main purpose of this page is to give an example of the workflow. For more information on the difference between rebasing vs merging, see this article.

The first thing to do when starting a new batch of work is to start from a clean branch on your machine.

 # from the main tidy3d frontend repo
git checkout pre/x.x
git pull origin pre/x.x
git checkout -b my_name/new_feature
2. Writing code#

Develop your code in this new branch, committing your changes when it seems like a natural time to “save your progress”.

If you are working on a new feature, make sure you add a line in the CHANGELOG.md file (if it exists in that repository) to summarize your changes.

3. Create a pull request on GitHub#

First, push your changes to your branch on GitHub.

In the GitHub website, create a pull request to merge your branch into pre/x.x.

Write some comments or a summary of changes in your pull request to be clear about what is being added/changed and why.

Before rebasing, you should make sure you have the latest version of develop, in case other work has been merged meanwhile.

git checkout pre/x.x
git pull origin pre/x.x
git checkout my_name/new_feature
git rebase -i pre/x.x

This will now open an editor that will allow you to edit the commits in the feature branch. There is plenty of explanations of the various things you can do.

Most probably, you just want to squash some of your commits. The first commit cannot be squashed - later commits get squashed into previous commits.

Once you save the file and close it, a new file will open giving you a chance to edit the commit message of the new, squashed commit, to your liking. Once you save that file too and close it, the rebasing should happen.

NB: The rebase may not work if there were conflicts with current develop. Ideally we should avoid that by making sure that two people are never working on the same part of the code. When it happens, you can try to resolve the conflicts, or git rebase --abort if you want to take a step back and think about it.

Finally, you now need to force push your branch to origin, since the rebasing has changed its history.

git push -f origin my_name/new_feature
4. Submit for review#

Every PR must have the following before it can be merged:

  • At least one review.

  • A description in the CHANGELOG of what has been done.

Every new major feature must also pass all of the following before it can be merged:

  • Frontend and backend tests by the developer (unless no code has changed on one or the other), as well as a new example notebook or a modification to an existing example notebook that utilizes the new feature. Intermediate reviews can happen, but these conditions must be met for the feature to begin to be considered for a merge.

  • Ensure any known limitations are listed at the top message in the PR conversation (e.g., does the feature work with the mode solver? The auto grid? Does it work, but not as well as it should?). The feature can be merged given the limitations if we make a decision to do that, but only if an error or warning is issued whenever a user could encounter them, and after the list has been moved to another PR or an issue to keep track.

  • If backend changes are present, review by one of the people well-versed with the solver (Momchil, Weiliang, Shashwat, Daniil).

  • If frontend changes are present, review by any member of the team and additional approval by Momchil or Tyler.

  • QA from any member of the team: playing around with the new feature and trying to find limitations. The goal is not to construct one successful example but to figure out if there is any allowed usage that may be problematic. An extra example notebook may or may not come out of this.

After this, you can notify Momchil that the branch is ready to to be merged. In the comment you can optionally also say things like “Fixes #34”. This will then automatically link that PR to the particular issue, and automatically close the issue.

This can be repeated as often as needed. In the end, you may end up with a number of commits. We don’t enforce a single commit per feature, but it makes the most sense if the feature is small. If the feature is big and contains multiple meaningful commits, that is OK. In any case, rebasing allows you to clean everything up.

NB: Only do this once you feel like you are fully done with that feature, i.e. all PR comments have been addressed, etc. This is not critical, but is nicer to only rebase in the end so as not to muddle up the PR discussion when you force push the new branch (see below).

Releasing a new tidy3d version#

This document contains the relevant information to create and publish a new tidy3d version.

Version Information Management#

The pyproject.toml is declarative (ie static) and provides information to the packaging tools like PyPi on what version is tidy3d. However, we also have a version.py file so that we can dynamically query tidy3d.__version__ within our python version. These two files need to be kept with the same version. This is achieved by using the bump-my-version utility as described in the following section. These files should not be manually updated.

The configuration of the way the version bumping occurs is described in the pyproject.toml.

Documentation Release#

The tidy3d-docs repository automatically mirrors the tidy3d repository. Specifically, these branches are automatically synced.

  • main

  • latest

  • develop

  • ‘pre/*’

  • ‘v*’

These branches are synced to the tidy3d-docs repo through the sync-readthedocs-repo Github action. You can read the latest versions synced in the action file. However, you need to configure how they appear in the documentation build in the readthedocs admin page. Only latest is the public version, others are private.

The latest branch holds the state of the docs that we want to host in latest version on the website. These are the latest docs (including new notebooks, typo fixes, etc.) related to the last official release (not pre-release).

The stable version of the docs on our website is built based on the last version tag which is not a pre-release tag (no rc ending).

Hot Fix & Submodule Updates#

To make a “hot fix” (eg fix a typo, add a notebook, update the release FAQ), just update the latest branch in tidy3d repo. This should automatically sync to tidy3d-docs, and trigger a docs rebuild. However, we should avoid this as this will cause the ``develop`` and ``latest branches`` to diverge. Ideally, these hot fixes could wait until the next pre/post-release to be propagated through.

NOTE: To avoid conflicts, ideally we should only update latest by merging develop in it, or at the very least we should make sure changes are propagated to both branches.

Notebooks Development#

All notebooks are now developed under the tidy3d-notebooks, and you can also develop this submodule under tidy3d/notebooks. Note that the submodule is linked to the develop branch of tidy3d-notebooks.

Say, you have done some changes onto the repository in tidy3d-notebooks and propagated them to the remote branch, you can run the following command:

poetry run tidy3d develop build-docs-from-remote-notebooks

This command will pull the latest changes onto your notebook submodule and build the documentation.