Skip to content

Latest commit

 

History

History
200 lines (127 loc) · 12.3 KB

CONTRIBUTING.md

File metadata and controls

200 lines (127 loc) · 12.3 KB

Contributing to Ameliorate

🔥🙂 Welcome, and thanks for considering contributing! 🙂🔥

All contributors (with GitHub accounts) will be recognized by being added to the Contributors section in the README 🙂. Please feel free to add yourself if you were missed, or reach out if you prefer not to be acknowledged in this way (reply to the comment that tags you when you're being added).

If you're new to open source, you'll probably find this open source guide useful.

If you're interested in playing a specific role for the project, check out Roles to Fill.

Code of Conduct

This project adheres to the Contributor Covenant code of conduct. By participating, you are expected to uphold this code.

Reaching out

If you'd like to reach out for any reason, here are a couple possible ways of doing so:

  • Discord - this is a casual way to mention something & have easy back-and-forth
  • Email [email protected] - easy to use if you’re unfamiliar with Discord

Providing feedback

There's plenty of room for improvement in this project, and any ideas, suggestions, concerns, etc, are greatly appreciated! You can reach out through the mediums above or create a GitHub Issue (which is slightly more formal, but this is the system used for managing the project’s work, so if you create an issue, you can track its status).

And here are some things that come to mind that’d be particularly useful for to share about:

  • People, groups, or organizations that might be interested in hearing about the tool
  • Anything in the experience that feels awkward
  • Bugs
  • Feature ideas
  • UI design advice
  • Problem information that doesn’t feel like it fits within the available node & edge types
  • Resources related to reaching mutual understanding & making decisions
  • Similar tools
  • Coding practices
  • Community building

There are also quite a few ideas that haven’t been fully thought out that could use some brain power, some specifically needing technical design and some needing feature/UX design.

Finding an issue to work on

Check out the first issues filter in the project backlog - good first issue Good for newcomers s have a narrow scope and are expected to entail a small number of changes, and ok first issue Clear & narrow scope but tougher than "good first issue" s have a narrow scope, but are expected to be a bit tougher. You can check out the backlog of all issues if you're feeling daring, plucky, or if this isn't your first rodeo. This list should be prioritized, but you don't need to limit yourself to the top.

Feel free to clarify any issues via commenting on the issue or asking in Discord. When you find an issue you want to work on, please comment on it to avoid duplicating work on it.

Note: be particularly wary of issues with a "needs [x]" label - these are expected to require significant design efforts.

Non-code contributions

There are many ways to contribute without coding! Providing feedback, building example diagrams, joining discourse sessions, sharing about the tool, creating/updating docs, etc. Check out the non-code no code changes are needed to accomplish this task issues for some specific tickets, and Roles to Fill for specific roles you can help fill.

Running the project

Make sure you have git, nvm (or your preferred node version manager), and docker installed. If you're on Windows, you may also need to install WSL to run the bash setup scripts.

Setup:

git clone https://github.com/amelioro/ameliorate.git # clone your forked repo instead if contributing
cd ameliorate

# install node version (and npm) specified in .nvmrc
nvm install

# install dependencies, commit hooks, env variables, seed db, build mock-auth server image
# see https://github.com/amelioro/ameliorate/blob/main/scripts/setupLocal.sh
npm run setup:local

Serve project on localhost:

npm run dev # runs postgres container, mock auth server, and the nextjs server

The mock authentication server will allow any username and password, and you can log in as any user by using the user's authId as the username. So if you want to log in as, e.g., the example seeded user, use "oauth-test-user" as the username.

Update project after pulling new changes:

# see https://github.com/amelioro/ameliorate/blob/main/scripts/update.sh
npm run update # run new migrations, install new dependencies

Running tests

The non-e2e tests run against smaller pieces of the system - they include api tests and unit tests. You can run the non-e2e tests without further setup:

npm run test

E2e tests

E2e tests perform actions via headless browser against a running instance of the app. They require a few steps to properly run:

npm run dev # start the app on localhost
# (you'll need to open a new terminal window because the previous command runs in the foreground)
npm run e2e:build # build e2e container (includes dependencies for running playwright)
# Note: the e2e container requires docker desktop version 4.29+ and enabling
# "Enable host networking" in the Features in Development settings - explanation https://github.com/amelioro/ameliorate/blob/main/e2e/runInContainer.sh#L15-L17

Then you can run e2e tests:

npm run e2e:test

And here are some more e2e-specific commands that might be useful:

npm run e2e:update-snapshots # run e2e tests and update snapshots if there are visual differences
npm run e2e:ui # open playwright UI for watching/managing e2e tests

Codebase overview

These are diagrams that might help provide high-level views of different pieces of the codebase:

Reading up on the tech listed in the Built with section of the readme will likely provide useful context.

Known deviations from standard usage of the above tech:

Core directory structure (here are helpful docs on how nextjs uses directories to serve pages and api routes):

src/
├─ api/: code for the api server
│ ├─ routers/: defines trpc endpoints
├─ common/: used in both front and back end, e.g. zod schema validations
├─ db/: e.g. migrations, db schema
├─ pages/: nextjs uses this dir to serve pages; these will use code in src/web/
│ ├─ api/: nextjs uses this dir to serve api routes; these will use code in src/api/
│   ├─ trpc/[trpc].page.ts: handles all trpc endpoints defined in src/api/routers/
├─ web/: code for the UI components

Working with the code

Generally, tooling has been set up to work with VS Code.

Code style

The eslint config is pretty strict, most notably the functional config. Strictness here is open for discussion, but being initially strict seemed like a good way to start (and learn some code styling practices, for the case of the extended configs).

To run linting:

npm run lint

Commit hooks

This project uses commit hooks to automate some tasks, and these are managed via husky. These tasks live in the .husky/ directory, and are explained below. If you want to skip commit hooks (e.g. if you want to quickly commit a wip), you can run git commit --no-verify.

Conventional commits

Conventional commits is a standard format for commit messages, used to aid readability of commit history. The format is <type>[optional scope]: <description> and an example commit message looks like feat(header): add link to feedback page. This commit message format, with these commit types, is enforced in a commit hook and github action via commitlint.

Prettier

Code formatting is managed by prettier, which is automatically run in a commit hook via lint-staged.

UX / UI style

For user experience & user interface design, please read uxui-guidelines.md.

Database

Consider using pg admin - it provides a convenient UI for manually managing db schema, viewing data, raw querying, etc.

Managing database schema

Use npm run migration:run to run migrations on your db that haven't been run yet, and to re-generate the prisma client (i.e. update types for queries based on schema changes). WARNING: this will ask to drop and recreate your db if your schema was modified outside of migrations; you can use npm run migration:deploy to run migrations even if your schema has diverged (and then you'll have to run npx prisma generate separately to re-generate the prisma client).

If you're writing migrations:

  • npm run migration:rollback to rollback the last migration that's been run on your db
  • npm run migration:generate to generate an up & down migration based on changes you've made in schema.prisma
  • each migration should either fully succeed or fully fail - prefer small migrations, but if you have multiple statements running in one migration, wrap them with BEGIN; and COMMIT; to ensure the statements are run in a single transaction (note: there's an open issue to improve error messages when transactions are used - removing these statements can help when debugging migration issues)
  • right now, only maintainers have credentials to the test database, so make a comment on the PR or in Discord to request migrations be run on the test database (an easier solution can be considered if this becomes a painpoint)

Helpful VS Code settings

  • extensions and settings for syntax highlighting, styling on save, making conventional commits, working with git; you should be prompted to install these extensions when you open the repo for the first time in vscode
  • tasks - run to view ts & linting errors in the vscode problem window

PR process

See the open source guide's Opening a pull request for instructions on opening a PR as well as generally-good PR practices.