Release Flow#

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

Feature Development Workflow#

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 splitting of branches into main, develop and separate feature branches is as explained there. 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 develop
git pull origin develop
git checkout -b my_name/new_feature

Create your feature rebase#

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

git checkout develop
git pull origin develop
git checkout my_name/new_feature
git rebase -i develop

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

Submitting to PR#

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.

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.

Release Flow

Contents