Skip to content

Latest commit

 

History

History
244 lines (163 loc) · 6.76 KB

HACKING.org

File metadata and controls

244 lines (163 loc) · 6.76 KB
Raw

Testing on other projects

The tools/test_branch.sh script builds 2 revisions of OCamlformat and run them on the sources of some projects. The list of tested project is (and can be edited) in test-extra/Makefile.

The projects sources are cloned into test-extra/code. Git is used to manage the script’s state:

  • staged changes are the diffs introduced by formatting with the first revision
  • unstaged changes are the diffs introduced by upgrading OCamlformat to the second rev

Release procedure

  • Make sure release milestone is green.
  • Review the impact of the release on real source code: In test-extra/Makefile, uncomment the extended list of projects to test and run tools/test_branch.sh -a "previous_release". Diffs should be discussed with the maintainers of these projects to gather feedback before continuing the release.
  • If a supported OCaml version does not have CI support, run test suite locally.
  • In CHANGES.md, change (unreleased) with the current version (a.b.c) and date. In README.md, update the recommended version to use in .ocamlformat files. Commit the changes.
  • Tag dune-release tag
  • Check that release binary has a release version number: dune build @install && dune install --prefix _install && ./_install/bin/ocamlformat --version && rm -rf _install should output just a.b.c
  • Linting dune-release lint
  • Amend the release commit if necessary and update the tag dune-release tag --force
  • Push the changes git push --tags
  • Release in automatic mode dune-release Until dune-release.1.5.0 is released the main branch of dune-release should be used.
  • Close release milestone.
  • Each release should be announced on https://discuss.ocaml.org/
  • Create a Windows asset:
    • install a compatible version of dune-release
    • checkout release tag: git checkout a.b.c
    • dune clean
    • dune-release distrib --skip-tests (ignore the error about a directory

    that can not be deleted)

    • check release version number:

    _build/ocamlformat-a.b.c/_build/install/default/bin/ocamlformat.exe --version should output just a.b.b

Backporting changes to a point release

Sometimes it is helpful to create a point release, but main contains changes that would be unsuitable for a point release.

Suppose the last release is 0.3.5, and since then, main contains new features F1 and F2 and a bugfix B.

release 0.3.5 -> feature F1 -> bugfix B -> feature F2
tag: 0.3.5                                 branch: main

Instead of reverting F1 and F2 in main, one can create a release branch for the 0.3 releases.

The end graph looks like this (if this is the first point release done this way in the 0.3.x series):

release 0.3.5 -> feature F1 -> bugfix B -> feature F2 -> merge commit
tag: 0.3.5                                               branch: main
            \                                          /
              -> bugfix B -> release 0.3.6  ----------
                             tag: 0.3.6
                             branch: 0.3

Or (if a previous point release has been made in the same way):

past  ->  merge commit -> feature F1 -> bugfix B -> feature F2 -> merge commit
              /                                       branch: main
             /                                       /
release 0.3.5  -> bugfix B -> release 0.3.6  -------
tag: 0.3.5                    tag: 0.3.6
                              branch: 0.3

Notes:

  • the release branch is always merged into main, not the other way around.
  • version detection relies on git tags, so main will be marked 0.3.5-x before the merge and 0.3.6-x after.

Step 1: prepare release branch

  • Is there an existing release branch?
    • No (this is the first time we are doing this on the 0.3.x series - first schema above).
      • Position to the latest 0.3.x release and create a branch named 0.3 here.
      • Example: git checkout 0.3.6 -b 0.3
    • Yes, branch 0.3 already exists (ie we already used this technique before - second schema above).
      • In this case, position to the 0.3 branch, which should be at the latest release (not a merge commit).
      • Example: git checkout 0.3
  • Cherry-pick bugfix (or bugfixes).
    • Example: git cherry-pick aaaaa bbbbb
    • These may not apply cleanly, so fix conflicts and QA (using CI, etc) as usual.
    • For the changelog in particular, the entry for the bugfix should go in a new section, and new features should not appear.

Changelog in main:

### unreleased

- Feature F1

- Bugfix B

- Feature F2

### 0.3.5

...

Changelog in 0.3 release branch:

### unreleased

- Bugfix B

### 0.3.5

...

Step 2: create release

  • Create release from branch 0.3 as usual. In particular, change “unreleased” to the new version, 0.3.6.
  • Continue process until PR to opam-repository is merged.

Step 3: merge release branch

  • Wait for opam-repository PR to be merged.
  • Merge release branch into main.
    • Not as a PR; as a manual merge.
    • Example: git checkout main followed by git merge 0.3.
    • This may conflict, in particular in the changelog.
    • To resolve the changelog conflict, add the point release section into main, and remove backported entries from the unreleased section.

Changelog in main before merging:

### unreleased

- Feature F1

- Bugfix B

- Feature F2

### 0.3.5

...

Changelog in 0.3 release branch:

### 0.3.6

- Bugfix B

### 0.3.5

...

End state:

### unreleased

- Feature F1

- Feature F2

### 0.3.6

- Bugfix B

### 0.3.5

...

Building on Windows

`ocamlformat` can be built as a native Windows binary using the `mingw64` toolchain under Cygwin. The following Cygwin packages are required:

  • `git`, `curl`, `unzip`
  • `m4`, `patchutils`, `make`
  • `mingw64-x86_64-binutils`, `mingw64-x86_64-gcc-core`, `mingw64-x86_64-headers`, `mingw64-x86_64-runtime`

The binary is built by executing `bash tools/build-mingw64.sh` from the root of the repository. The first time the script is launched, it will install `opam` in the subdirectory `_build-mingw64` and use it to install all the dependencies of `ocamlformat` and then build the binary. Subsequent launches of the script will only rebuild `ocamlformat`. If you need to start from scratch again, simply remove the `_build-mingw64` directory.

This script can also be triggered as a GitHub Action named `build-mingw64` which will build the binary in a GitHub worker and upload it back to GitHub. To retrieve it, select the Action run in question and scroll down to “Artifacts”.