Docs

docs/distribution/nightly.md

@@ -8,31 +8,75 @@ order: 10
 
 # Nightly Builds
 
-This document describes the infrastructure for nightly builds.
+This document describes the infrastructure for automated nightly builds.
 
 <!-- MarkdownTOC levels="2,3" autolink="true" -->
 
-- TODO
+- [Triggering the Build](#triggering-the-build)
+- [Nightly Build Versions](#nightly-build-versions)
+- [Release Notes](#release-notes)
 
 <!-- /MarkdownTOC -->
 
-## Scheduled Builds
+## Triggering the Build
 
-After each weekday, at 4am UTC a scheduled workflow prepares a release from the latest commit on the `main` branch.
+The build may be triggered on two possible events:
 
-A new release is not made if there were no new commits to `main` since the previous release.
+- automatically, at 4am UTC after each working day (that is, on Tuesday to
+  Saturday),
+- manually, if a commit with message containing `[release: nightly]` is pushed
+  to the `main` branch.
 
-Each nightly build gets the current date appended to the version and since commits on `main` should have versions marked as SNAPSHOT (for example `1.2.3-SNAPSHOT`), the nightly release version will then look like `1.2.3-SNAPSHOT.1970-01-01`.
+The nightly build is based off of the state of the `main` branch at the moment
+when it was triggered.
 
-## Manual Builds
+However, when a nightly build is triggered (by any of the two above conditions),
+it will only proceed if there are any changes. That is, if the current commit is
+the same as the one used for the previous nightly build, the build will not
+proceed, because there are no changes.
 
-It is possible to trigger a nightly release manually by adding `[release: nightly]` to the commit message.
+Thanks to
+[GitHub's concurrency settings](https://docs.github.com/en/actions/reference/workflow-syntax-for-github-actions#concurrency),
+only one nightly or regular release job may be running at a given time. If a
+build is triggered when another one is in progress, it will be pending until the
+first one finishes.
 
-TODO: which branches this works on, handling collisions
+## Nightly Build Versions
 
-## Release Retention
+The nightly build will modify the version (which is set in `build.sbt`) to
+indicate that this is a specific nightly build.
 
-Only the 3 most recent nightly releases are kept. When a nightly release finishes building it removes any older releases to keep only the most recent 3.
+If the version does not include a `SNAPSHOT` suffix, it is added. Then the
+current date is appended. Moreover, if the build is not the first nightly build
+to be done on a given day, an increasing numeric suffix is appended, to
+differentiate between builds from a single day.
 
-Thus, setting a nightly version for a project will require updating it very soon (currenty after about 3 days). The launcher issues a warning when creating a project with a nightly version and if the version is not available it explains that this may be due to the retention policy.
+For example, if `build.sbt` specifies the version to be `1.2.3` or
+`1.2.3-SNAPSHOT`, the nightly build based off of that version, triggered on 1st
+of February 2021 will result in version `1.2.3-SNAPSHOT.2021-02-01`. If a
+subsequent build based off of the same version is triggered on the same day it
+will be `1.2.3-SNAPSHOT.2021-02-01.1` etc.
 
+Only the 3 most recent nightly builds are kept in the repository, any older
+builds are removed from releases.
+
+## Release Notes
+
+Each PR should update the first, `Enso Next`, section in `RELEASES.md`. These
+changes will be later moved to the specific section for the full release. This
+section is also used to fill the release notes for the nightly builds.
+
+Most PRs should update the release notes, so there is a PR check that ensures
+the file was modified. However in some situations there is no need to update the
+notes. If any commit included as part of a PR includes `[no-changelog]` within
+its message, that check is ignored.
+
+The changelog should keep consistent formatting:
+
+- each version should be delimited by a top-level section (`#` in Markdown),
+- the first section should always be called `Enso Next`,
+- all subsequent sections should be called `Enso <version> (<date>)`.
+
+A heuristic check is ran for PRs, checking that at least the first two sections
+satisfy the above requirements - which is necessary for the nightly build
+pipeline to be able to correctly infer the release notes.

lib/scala/runtime-version-manager/src/main/scala/org/enso/runtimeversionmanager/components/Engine.scala

@@ -70,7 +70,7 @@ case class Engine(version: SemVer, path: Path, manifest: Manifest) {
 
   /** Specifies if the engine version comes from a nightly release.
     *
-    * See `docs/distribution/nightly.md` for more information. TODO [RW] docs
+    * See `docs/distribution/nightly.md` for more information.
     */
   def isNightly: Boolean = Engine.isNightly(version)
 }

lib/scala/runtime-version-manager/src/main/scala/org/enso/runtimeversionmanager/runner/Runner.scala

@@ -54,7 +54,7 @@ class Runner(
           "--new-project-name",
           name
         ) ++ authorNameOption ++ authorEmailOption ++ additionalArguments
-      // TODO [RW] this warning will not be clearly visible in the IDE, do we want some other mechanism there? It would most likely require modifying the protocol.
+      // TODO [RW] reporting warnings to the IDE (#1710)
       if (Engine.isNightly(engineVersion)) {
         Logger[Runner].warn(
           "Creating a new project using a nightly build. Nightly builds may " +