Previously, releases were always made from a point in the revision history of the `main` branch (typically the tip of
the branch at the time of the release). Although the simplicity of this approach is nice, it can be limiting in some
cases. For this reason, the project is switching to using a "trunk-based" development strategy, as described here:
https://trunkbaseddevelopment.com/
This approach allows making releases at any time that consist of the arbitrary subset of revisions suitable for shipping
to the users at that time. The commits that should be included in the release are cherry-picked to a release branch and
the tag created on that branch.
This means that:
- PRs can be merged to the `main` branch as soon as they have passed review rather than having to postpone the merge of
changes that are not ready to be included in the next release.
- Releases don't need to be postponed if the prior revision history on the `main` branch contains changes that are not
ready to be included in the release.
The documented release procedure must be adjusted to reflect the new development strategy.
CI System Adjustments
---------------------
The status of the GitHub Actions workflows should be evaluated before making a release. However, this is not so simple as
checking the status of the commit at the tip of the release branch. The reason is that, for the sake of efficiency, the
workflows are configured to run only when the processes are relevant to the trigger event (e.g., no need to run unit
tests for a change to the readme).
In the case of the default branch, you can simply set the workflow runs filter to that branch and then check the result
of the latest run of each workflow of interest. However, that was not possible to do with the release branch since it
might be that the workflow was never run in that branch. The status of the latest run of the workflow in the default
branch might not match the status for the release branch if the release branch does not contain the full history.
For this reason, it will be helpful to trigger all relevant workflows on the creation of a release branch. This will
ensure that each of those workflows will always have at least one run in the release branch. Subsequent commits pushed to
the branch can run based on their usual trigger filters and the status of the latest run of each workflow in the branch
will provide an accurate indication of the state of that branch.
Branches are created for purposes other than releases, most notably feature branches to stage work for a pull request.
Due to the comprehensive nature of this project's CI system, it would not be convenient or efficient to fully run all CI
workflows on the creation of every feature branch.
Unfortunately, GitHub Actions does not support filters on the `create` event of branch creation like it does for the
`push` and `pull_request` events. There is support for a `branches` filter of the `push` event, but that filter is an
"AND" to the `paths` filter while this application requires an "OR". For this reason, the workflows must be triggered by
the creation of any branch. The unwanted job runs are prevented by adding a `run-determination` job with the branch
filter handled by Bash commands. The other jobs of the workflow use this `run-determination` job as a dependency, only
running when it indicates they should via a job output. Because this minimal `run-determination` job runs very quickly,
it is roughly equivalent to the workflow having been skipped entirely for non-release branch creations.
The Arduino IDE release includes several tool dependencies. Unstable versions of these tools may be pinned provisionally
for use with the development version of Arduino IDE, but production releases of Arduino IDE must use production releases
of the tool dependencies.
The release manager should check the tool versions before making a release, but previously this step was not mentioned
in the release procedure documentation.
On every startup, the Arduino IDE checks for new versions of the IDE. If a newer version is available, a
notification/dialog is shown offering an update.
"Newer" is determined by comparing the version of the user's IDE to the latest available version on the update channel.
This comparison is done according to the Semantic Versioning Specification ("SemVer").
In order to facilitate beta testing, builds are generated of the Arduino IDE at the current stage in development. These
builds are given an identifying version of the following form:
- <version>-snapshot-<short hash> - builds generated for every push and pull request that modifies relevant files
- <version>-nightly-<YYYYMMDD> - daily builds of the tip of the default branch
The previous release procedure caused the <version> component of these to be the version of the most recent release.
During the pre-release phase of the project development, all releases had a pre-release suffix (e.g., 2.0.0-rc9.4).
Appending the "snapshot" or "nightly" suffix to that pre-release version caused these builds to have the correct
precedence (e.g., 2.0.0-rc9.2.snapshot-20cc34c > 2.0.0-rc9.2). This situation has changed now that the project is using
production release versions (e.g., 2.0.0-nightly-20220915 < 2.0.0). This caused users of "snapshot" or "nightly" builds
to be presented with a spurious update notification on startup.
The solution is to add a step to the end of the release procedure to do a minor bump of the version metadata after
creating the release tag.
This means that the metadata bump traditionally done before the creation of the release tag will already have been done
in advance for patch releases. However, it will still need to be done for minor or major releases.
The release procedure documentation is hereby updated to produce correct tester and nightly build version precedence.
The metadata bump step is moved from before to after the tag creation step, replaced by a new step to verify the version
before the tag creation, updating it in the event it is not a patch release. Both those steps may require updating the
metadata. As an alternative to maintaining duplicate copies, each step links to a single copy of the fairly complex
instructions for doing so. The structure of the document is adjusted to accomodate this, by placing the steps of the
procedure under a "Steps" section and creating a new "Operations" section to contain any such shared content.
The release procedure is a set of steps which must be performed in a specific sequence. This fact is more effectively
communicated by formatting it as an ordered list.
Previously the instructions for updating the npm package metadata, submitting a PR for that, and merging the PR was in
the same section as the tag push instructions in the release procedure documentation.
These two operations are distinct from each other. Mashing them into a single step makes the release procedure document
difficult to read and the process more prone to error.
For this reason, a dedicated step is used for each of the two things.
- From now on, NSFW service disposes after last reference
is removed. No more 10sec delay.
- Moved the temp workspace deletion to a startup task.
- Can set initial task for the window from electron-main.
- Removed the `browser-app`.
Closes#39
Signed-off-by: Akos Kitta <a.kitta@arduino.cc>
Previously, information about project development was stored in a file named BUILDING.md in the root of the repository.
That content is hereby moved to the file docs/development.md. This will provide the following benefits:
- Broaden the scope of the file to all information related to development rather than building only
- Store all documentation content under a single folder instead of randomly putting some in the root and others under
docs
An internal release procedure document was created separately from the documentation hosted in this repository. That
internal document became significantly more comprehensive and up to date than the unmaintained documentation in this
repository.
In order to avoid either the burden of maintaining two copies of the same information, or more likely the out of sync
state between the information in the two resulting from lack of such maintenance, a single document will be maintained
here in this repository.
The superior version of the information from the internal document is hereby migrated to the repository where it will be
maintained from here on.
Previously, the procedure for creating a new release of the project was included in the development documentation.
This information is distinct from the rest of the contents of that file in that it is not of any value or interest to
most contributors from the community since only project maintainers will ever create a release. This meant that it make
the document less readable and approachable without adding significant value in return.
The information is still essential to the project maintainers, so it must not be removed, but it can be moved to a
dedicated file under the existing `docs/internal/` folder that is specifically intended for storing such information.
The original location of the project repository was `bcmi-labs/arduino-editor` and some of the internal development
documentation for the project contains references to the repository.
This documentation was not updated at the time the repository was moved to the current home in `arduino/arduino-ide`.
