Skip to content

Latest commit

 

History

History
104 lines (70 loc) · 4.02 KB

DEVELOPER.md

File metadata and controls

104 lines (70 loc) · 4.02 KB
Raw

Fourmolu — Developer notes

Contributing

Some things to keep in mind when making changes:

  • Make the minimal amount of changes
    • Avoid refactoring where possible, don't reformat untouched code
    • Since we continuously merge in changes from Ormolu, reducing the number of potential conflicts goes a long way towards maintainability of this project.

Release a new version

To release a new version, do the following workflow:

  1. Create a new branch

    1. Bump version in fourmolu.cabal

      • All version bumps should follow PvP

    2. Curate CHANGELOG.md, creating a new section for this version and moving everything previously in Unreleased into the new section (keeping Unreleased as a section)

      It should roughly follow this format:

      ## Fourmolu 1.2.3.0

* Fourmolu-specific change 1
* Fourmolu-specific change 2

### Upstream changes:

#### Ormolu 2.3.4.0

* Ormolu change 1

#### Ormolu 2.3.3.0

* Other change

    3. Add comments to new features indicating when it was added (e.g. @since v2.0.0)

    4. Run stack haddock or cabal haddock and skim through documentation

  2. Create PR as usual and merge into master

    1. In the test_latest CI job, check the output of the stack sdist step for any warnings.

  3. Upload the package to Hackage

    1. Download the fourmolu-*.tar.gz file from CI artifacts
    2. Upload tarball to Hackage

Merging upstream

Fourmolu aims to continue merging upstream changes in Ormolu. Whenever Ormolu makes a new release (ideally within a week), the following steps should be run to merge the changes into Fourmolu.

  1. cd into your local copy of the Fourmolu repository
  2. Add Ormolu as an upstream remote: git remote add ormolu git@github.com:tweag/ormolu
  3. Check out a new branch: git switch -c merge-ormolu
  4. Pull Ormolu's git history: git fetch ormolu --no-tags
  5. Find the commit corresponding to the new Ormolu version and merge it: git merge <commit>
  6. (Recommended) Switch to diff3 conflicts: git checkout --conflict=diff3. This provides more context that might be helpful for resolving conflicts. See docs.
  7. Resolve conflicts + finish merge: git merge --continue
    • Rewrite the default commit message to "Merge ormolu-X.Y.Z"
  8. Run tests to ensure everything works well: stack test

Resolving conflicts

  • Conflicts at the following paths should be resolved by keeping the files DELETED (i.e. if there's a "deleted by us" conflict, use git rm to avoid adding the file to our repo):

    • .github/
    • .buildkite/
    • DESIGN.md
    • default.nix
    • nix/
    • shell.nix

  • Conflicts at the following paths should be resolved by throwing out Ormolu's changes and keeping our changes (i.e. if there's a conflict, use git checkout --ours):

    • stack.yaml

  • The state of the following paths should be the same as they are in Ormolu (i.e. if there's a conflict, use git checkout --theirs)

    • expected-failures/

  • Any Ormolu additions to CHANGELOG.md should be added under a ### Upstream changes: header in the Unreleased section of CHANGELOG.md, with the Ormolu headers bumped to ####. See the CHANGELOG format in the "Release a new version" section.

  • Be careful when editing fourmolu.cabal to only change shared things (e.g. tested-with) and not Fourmolu things (e.g. name or version).

Update tests

  • Regenerate test files

    1. Comment out the line in PrinterSpec.hs after the "UNCOMMENT NEXT LINE TO REGENERATE OUTPUT FILES" comment
    2. Run tests and commit any new *-four-out.hs files

  • Remove any redundant Fourmolu output files

    find data/examples -name '*-four-out.hs' -print0 | while IFS= read -r -d '' f; do
    dir=$(dirname "$f")
    name=$(basename "$f" '-four-out.hs')
    src="${dir}/${name}.hs"
    if [[ ! -f "$src" ]]; then
        rm -v "$f"
    fi
done