Remove Evan's CLA, adjust contributing.md accordingly, refine extra/readme.md

Author: supermario

.github/CONTRIBUTING.md

@@ -1,43 +1,25 @@
-# Contributing to Elm
+# Contributing to the Lamdera compiler
 
-Thanks helping with the development of Elm! This document describes the basic
-standards for opening pull requests and making the review process as smooth as
-possible.
+Thanks contributing to the Lamdera compiler!
 
-## Licensing
-
-You need to sign the [contributor agreement](ContributorAgreement.pdf)
-and send it to <info@elm-lang.org> before opening your pull request.
+The Lamdera **compiler** is a free, open-source and open-contribution [un-fork of the Elm compiler](https://dashboard.lamdera.app/releases/open-source-compiler).
 
 ## Style Guide
 
-  * Haskell &mdash; conform to [these guidelines][haskell]
-  * JavaScript &mdash; use [Google's JS style guide][js]
-
-[haskell]: https://gist.github.com/evancz/0a1f3717c92fe71702be
-[js]: https://google.github.io/styleguide/javascriptguide.xml
+We don't have a particular style enforcement tool in place, but generally
+we prefer Elm-like layout that's indented with two spaces, with no trailing
+whitespace.
 
 ## Branches
 
-  * [The master branch][master] is the home of the next release of the compiler
+  * [The lamdera-next branch][lamdera-next] is the home of the next release of the compiler
     so new features and improvements get merged there. Most pull requests
-    should target this branch!
-
-  * [The stable branch][stable] is for tagging releases and critical bug fixes.
-    This branch is handy for folks who want to build the most recent public
-    release from source.
+    should target this branch, it is the repo default branch.
 
-[master]: http://github.com/elm-lang/elm/tree/master
-[stable]: http://github.com/elm-lang/elm/tree/stable
+[lamdera-next]: https://github.com/lamdera/compiler
 
-If you are working on a fairly large feature, we will probably want to merge it
-in as its own branch and do some testing before bringing it into the master
-branch. This way we can keep releases of the master branch independent of new
-features.
+## Development guide
 
-Note that the master branch of the compiler should always be in sync with the
-master branch of the [website][], and the stable branch of the compiler should
-always be in sync with the stable branch of the [website][]. Make sure that
-your changes maintain this compatibility.
+Check out the [extra/readme.md](extra/readme.md) for more information on how to get started with development.
 
-[website]: https://github.com/elm-lang/elm-lang.org
+If you're planning on embarking on a feature, come chat with us on the [Lamdera Discord](https://dashboard.lamdera.app/docs/discuss) as it's possible we're already working on it, or have some thoughts that will be helpful to get the best result and ensure it can be merged quickly.

ContributorAgreement.pdf

@@ -4,7 +4,7 @@ Elm is [a delightful language for reliable webapps](https://elm-lang.org/).
 
 The Lamdera compiler extends the official Elm compiler with tooling that works for any regular Elm frontend project, as well as specific features for Elm projects on [Lamdera: A delightful platform for full-stack Elm web apps](https://lamdera.com).
 
-The Lamdera **compiler** is free, open-source and open-contribution [un-fork of the Elm compiler](https://dashboard.lamdera.app/releases/open-source-compiler).
+The Lamdera **compiler** is a free, open-source and open-contribution [un-fork of the Elm compiler](https://dashboard.lamdera.app/releases/open-source-compiler).
 
 The Lamdera **platform** is a paid service with a free tier to try, and is how we keep our work funded and sustainable.
 

README.md

@@ -9,43 +9,31 @@ The integration philosophy is:
 - Inject as small a surface area into actual compiler code as feasibly possible
   - You'll see this done with certain tricks using `&` and `$` to, wherever possible, only add additional lines to source, without modifying any existing lines
   - This means merge conflicts are minimized when trying to stay up to date with upstream Elm Compiler
-  - Sometimes entire functions are added to the bottom of files, usually when the current file defines a bunch of types that are needed and it's messier to have it external
+  - Sometimes entire functions are added to the bottom of core files, this is usually when the current file defines a bunch of types that are needed in the extension code, and it's problematic/messier to externalise that code and cause cyclic dependencies
 
 The idea is that searching the project for `import.*Lamdera` and `@LAMDERA` will reveal every single `/builder` and `/compiler` core file that has some Lamdera related modification.
 
-Alternatively the [diff of `master` and `lamdera` branches](https://github.com/lamdera/compiler/compare/master...lamdera) gives a nice overview of all modifications in the "Files Changed" view.
+Alternatively the [diffing `elm/compiler` and `lamdera/compiler`](https://github.com/lamdera/compiler/compare/master...lamdera) gives a nice overview of all core file modifications in the "Files Changed" view.
 
 Otherwise:
 
-  - Use Elm compiler source liberally inside `/extra`
+  - Reference/use Elm compiler source liberally inside `/extra`
   - We don't want to reinvent the wheel on core compiler concepts, and can lean heavily on Haskell's type system to tell us when there are problems due to core type changes upstream in future
-  - Future developers might find things might seem obviously duplicated - if there's no comment and blame history is not helpful, it was likely accidental (didn't know compiler already had that functionality/code) or transient (i.e. features carried up from 0.19 over the years)
+  - Future developers might find things that might seem obviously duplicated - if there's no comment and blame history is not helpful, it was likely accidental (didn't know compiler already had that functionality/code) or transient (i.e. features carried up from 0.19 over the years)
 
 If in doubt, please ask!
 
 ### Setup
 
-```
-brew install gcc pkg-config      # some headers like 'linux/random.h' are implicitly required to build Haskell libs
-brew install icdiff   # used for nice side-by-side diffs in test output
-git submodule init && git submodule update # Get and update Git submodules for this project
-stack install hindent # used for debugging haskell values
-```
-
-
-### Tests
+:warning: We'd like to move to `devbox` to make this a one-shot env setup in future; contributions welcome.
 
-The `test` folder contains tests for aspects of the additional functionality. Most are at the acceptance test level, these have been the most useful so far.
-
-The test framework is a very lightweight vendored copy of `EasyTest.hs`, defined entirely in that one file. There are some `test/Test/Helpers.hs` too.
-
-The easiest way to run is from the project root:
+In the meantime, here's our setup on MacOS:
 
 ```
-$ TOKEN="..." LDEBUG=1 LOVR=~/lamdera/overrides stack ghci
-λ: Test.all
-...
-✅  38 tests passed, no failures!
+brew install gcc pkg-config                # some headers like 'linux/random.h' are implicitly required to build Haskell libs
+brew install icdiff                        # for nice side-by-side diffs in test output
+git submodule init && git submodule update # setup Git submodule deps for this project
+stack install hindent                      # used for debugging haskell values
 ```
 
 ### Developing
@@ -82,11 +70,36 @@ By default it's `target = Test.all`, so `:rr` will recompile and run all tests.
 
 Press up arrow to get history of prior commands!
 
-#### Tests
+#### Debugging in VSCode
+
+https://marketplace.visualstudio.com/items?itemName=phoityne.phoityne-vscode
+
+```
+stack install haskell-dap ghci-dap haskell-debug-adapter
+```
+
+
+
+### Tests
+
+:warning: The compiler tests need work, a few of them are not isolated (i.e they reach out into the world and expect things to exist).
+
+The `test` folder contains tests for aspects of the additional functionality. Most are at the acceptance test level, these have been the most useful so far.
+
+The test framework is a vendored copy of the very lightweight [`easytest`](https://github.com/joelburget/easytest) lib, defined entirely in that one file. There are some `test/Test/Helpers.hs` too.
+
+The easiest way to run is from the project root:
+
+```
+$ TOKEN="..." LDEBUG=1 LOVR=~/lamdera/overrides stack ghci
+λ: Test.all
+...
+✅  38 tests passed, no failures!
+```
 
-`test/Test.hs` is the entrypoint for all tests. Use `Test.all` in ghci to run everything (it is also the `:rr` target by default).
+`test/Test.hs` is the entrypoint for all tests. Use `Test.all` in ghci to run everything (it is also the `:rr` target by default, see notes above).
 
-Using the test framework in `test/EasyTest`, a vendored version of [easytest](https://github.com/joelburget/easytest) back when it had fun emojis! It's only a single file and easy to read.
+Using the test framework in `test/EasyTest`, a vendored version of  back when it had fun emojis! It's only a single file and easy to read.
 
 
 #### Testing functions directly