README

This repository contains a test suite for patches that the elm-janitor packages stack on top of the official Elm core packages.

It is also useful to develop or evaluate patches to core Elm packages and their kernel code.

Every forked core package from elm-janitor is a git submodule, so best clone this repository with --recurse-submodules.

Usually, you would apply all patches and then run the test suites.

After that, you can either verify new patches, or work on your own changes.

Download and apply patches

First, you should set the $ELM_HOME environment variable

# fish
set ELM_HOME (pwd)/elm-home
# sh
ELM_HOME=`pwd`/elm-home
# Windows CMD.exe
set ELM_HOME=%cd%\elm-home

If you use direnv, you can run direnv allow to set it to ./elm-home.

Then you can either

1) Use the git submodules
and run ./link-all-packages.sh.

Note: If you cloned this repository without checking out the submodules, you can do that by running git submodule update --init --recursive

2) Or use the elm-janitor/apply-patches script
to apply all the patches

# With deno
❯ deno run --allow-env=ELM_HOME,HOME --allow-read --allow-write --allow-net=github.com,codeload.github.com,api.github.com  https://raw.githubusercontent.com/elm-janitor/apply-patches/main/deno/cli.ts --all

# Or with node.js
❯ npx elm-janitor-apply-patches --all

After that, you can proceed to run the test suites.

Test suites

1. Tests that only need an Elm test runner, see ./elm-tests/README.md
2. Tests that need a fake browser environment, see ./js-tests/README.md
3. Tests that need an actual browser, see ./browser-tests/README.md

Regression tests

Applying the changes of elm-janitor should not introduce regressions.
Not all core packages have tests, for those we could create a suite (TODO).

But we can run these tests

cd packages/core/tests
npx [email protected] tests

After including elm-janitor/json#1 we can also execute the tests of the json package.

cd packages/json/tests
npx [email protected] tests

Note: If you used the elm-janitor/apply-patches script, those packages/*/tests directories won't exist.

Scripts

To add a new package as a git submodule into ./package/ and link it into the ./elm-home/0.19.1/packages/elm/<package>/<version> directory, execute

./add-package.sh core 1.0.5

If you only want to update the link from ./package/<package> to ./elm-home/0.19.1/packages/elm/<package>/<version>, execute

./link-package.sh core 1.0.5

After running tests, the git submodules might be marked as dirty. This can be usually fixed by removing files that the Elm compiler generates on every run with

./clean-git-submodules.sh

If you want to test or create pull requests for the Elm core packages, you can add the original repositories as remote upstream to every git submodule by executing

./add-upstream-git-remotes.sh

Usage and development hints

If you want to propose new fixes to be included into the elm-janitor packages, have a look at this document on how to create branches from pull requests and how to add them to the stack of changes.

Default branch of submodules

Inside ./.gitmodules, the current "default" stack-x.y.z branch is selected.
If a new upstream version should be patched and used as default, we need to update the branch name there.

Switching between multiple versions fast

If you want to toggle between versions of a package, you can do the following:

# Remove `elm/http` from ./elm-home and let the Elm compiler install the upstream version during the next build
./remove-cached-package.sh http
# Verify that the tests for elm/http fail using the upstream version
npx jest tests/http-*
# And then use the latest state of the submodule packages/http as elm/http v2.0.0
./link-package.sh http 2.0.0
# After that, the tests should no longer fail
npx jest tests/http-*

Updating to the latest published stack-x.y.z branch

To check out the latest published commit of every janitor package, you can execute this:

git submodule update --remote

If you want to look at the changes first, run

git submodule summary

Note: For both commands, you can speed them up by reducing the scope and appending the submodule path, e.g. packages/core.

Compiler errors inside the js kernel code

If you make changes to the core packages and use them inside another project (or in these tests), you won't see nice error messages, but instead get a very generic PROBLEM BUILDING DEPENDENCIES error.

Then it can be helpful to run the Elm compiler on the changed Elm source file, e.g. cd packages/core && elm make --output=/dev/null src/Char.elm (see for instance in this issue).

If you change the js kernel code, you are completely on your own and will have to step through the generated js code to find issues.

Verified fixes

This repository can verify that the following issues are solved by elm-janitor patches.

• From https://github.com/elm-janitor/browser/tree/stack-1.0.2 (commit 53e3caa)
  • No fixes
• From https://github.com/elm-janitor/bytes/tree/stack-1.0.8 (commit 2bce2ae)
  • No fixes
• From https://github.com/elm-janitor/core/tree/stack-1.0.5 (commit 3729650)
  • Fixes elm/core#942
  • Fixes elm/bytes#15
  • Fixes elm/core#952
  • Fixes elm/core#1137
• From https://github.com/elm-janitor/file/tree/stack-1.0.5 (commit 7c7db2c)
  • Fixes elm/file#17 (bug in iOS <= 13)
• From https://github.com/elm-janitor/http/tree/stack-2.0.0 (commit e065c97)
  • Fixes elm/http#66
• From https://github.com/elm-janitor/json/tree/stack-1.1.3 (commit 24a7c9a)
  • TODO elm/json#9
  • TODO elm/json#22
  • Fixes elm/core#904
  • Fixes elm/json#13
  • Fixes elm/json#15
• From https://github.com/elm-janitor/parser/tree/stack-1.1.0 (commit a61f4ae)
  • Fixes elm/parser#2
  • Fixes elm/parser#9
  • Fixes elm/parser#20
  • Fixes elm/parser#46
  • Fixes elm/parser#53
• From https://github.com/elm-janitor/project-metadata-utils/tree/stack-1.0.2 (commit 5fb7e5a)
  • Fixes elm/project-metadata-utils#19
• From https://github.com/elm-janitor/random/tree/stack-1.0.0 (commit 1cf1144)
  • Fixes elm/random#21
  • Fixes elm/random#22
• From https://github.com/elm-janitor/time/tree/stack-1.0.0 (commit 7b97ef5)
  • No fixes
• From https://github.com/elm-janitor/virtual-dom/tree/stack-1.0.3 (commit 962f555)
  • No fixes