●Contributing

We're honored that people want to contribute to our little project.

Let's build a public good together :)

What to work on

Our priorities now fall in 3 buckets:

  • bugs: mailing should be relatively bug-free
  • compatibility: mailing should work in many environments
  • features: mailing should be fun and powerful for developing and sending emails

The first 2 categories are straightforward, go ahead and grab an open issue by assiging yourself or calling dibs with a comment. Even submitting a cold PR with a bugfix is welcome.

The third category is trickier. Adding features can complicate existing use-cases or make mailing more difficult to use so we want to be careful. Therefore, let's discuss new features in discussions or issues before working on them. If you want to hack together a prototype to flesh out your idea before discussing that's cool too, just know that it's not likely to be merged as-is.

Developing Mailing

Dev Setup

git clone git@github.com:sofn-xyz/mailing.git
cd mailing
yarn
yarn dev

yarn dev starts the cli in dev mode

Develop using a demo next app

For development, you may want to have a demo next app that pulls in your changes. We've had success using yalc and the following flow:

  • Register mailing as a local package with yalc: in the packages/cli directory, run yalc add.
  • Create a new next app in your projects directory by running yarn create next-app --typescript for a typescript app OR yarn create next-app for a js app
  • In the next app, run yalc add mailing, this creates node_modules/mailing and node_modules/.bin/mailing. (Note: yarn link does not add the bin file, which is why yalc is prefered)
  • Make your changes in mailing
  • Run yarn build in the mailing root directory to create new dist files
  • Run yalc push in the mailing root directory to both publish your changes (yalc publish) and pull them in to your next app (yalc update)

Run jest tests

Run yarn test to run the jest tests. These tests do not require the preview server to be running.

Run integration tests

Run yarn test:integration to run the integration tests. These tests are written in jest, but interact with a real database. You do not need to start the Mailing server to run these tests -- a server running in test mode will start automatically when you run this command. Some env variables must be set in order for these test to run, see the "Integration tests" section of .env.example for details.

Run cypress tests for the preview server

  • Start a mailing preview server on localhost:3883
  • cd into packages/cli and run yarn cypress run

Run embedded jest tests for the preview server

During the framework test process described below, the jest tests in scripts/e2e_test/jest_tests are copied into the directory where each target framework is installed and run. Before testing them in the framework install context, however, you will want to make sure they pass on the latest build by running yarn build and then yarn e2e:jest in the mailing project root.

Framework tests

The directory scripts/e2e_test contains framework tests targeting supported frameworks that should be run before every public npm release. Each test uses the yarn create command to create new projects from their create-* starter kits and then runs the cypress cli tests contained in packages/cli/cypress and the jest tests contained in scripts/e2e_test/jest_tests.

The frameworks currently covered by the tests are:

  • standalone (no framework)
  • turbo (Turbo monorepo)
  • next_ts (Next.js with Typescript)
  • next_js (Next.js without Typescript)
  • redwood_ts (Redwood with Typescript)
  • redwood_js (Redwood without Typescript)
  • remix_ts (Remix with Typescript)
  • remix_js (Remix without Typescript)

Initial test setup

  • In the project root, run asdf install to install ruby 3.1.2
  • In the directory scripts/e2e_test, run bundle install to install the required ruby gems

Run the framework tests

  • In the project root, run yarn test:e2e to run the full framework test suite, including cypress and jest tests for all supported frameworks.

This will instantiate each framework, add mailing with yalc, and then run the cypress tests contained in packages/cli/cypress and the jest tests contained in scripts/e2e_test/jest_tests.

Run the framework tests with advanced options

The underlying ruby script bundle exec ruby e2e/cli.rb supports some options for running:

  • --app=redwood_ts to run the tests only on the specified framework. See e2e/app.rb for the list of supported frameworks
  • --skip-build to skip the yarn build part of the script, useful when debugging something unrelated to the build
  • --update-snapshot if you need to update the snapshots in the framework tests. This will run jest with the -u option and then copy
  • --rerun to skip the framework install part of the script, useful when debugging something in your cypress tests unrelated to the build or the framework install. This will use the framework installs that are present in the runs/latest directory, i.e. the assumption is you've run a test against some framework(s) and you now want to re-running them after adjusting your cypress tests. the updated snapshots back to mailing.

Cache the framework installs for faster runs

  • Use the --save-cache flag to save each framework install (before mailing is added) to the cache directory. Subsequent test runs will start with a copy of the cache instead of running yarn create and yarn install, which will speed things up 🏎 If you need to resetthe cache, e.g. if you want to test a newer version of the framework or if the framework install process changes, you can delete the cache directory or the subdirectory containing the specific framework you are targeting.