Skip to content

Latest commit

 

History

History
115 lines (70 loc) · 7.77 KB

CONTRIBUTING.md

File metadata and controls

115 lines (70 loc) · 7.77 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.

Code of Conduct

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

Providing feedback

There's plenty of room for improvement in this project, and any ideas, suggestions, concerns, etc, are greatly appreciated! Reach out any way you know how, but here are a few mediums you can use:

  • Discord - this is a casual way to mention something & have easy back-and-forth; there’s also specifically a channel for #ideas-and-feedback
  • GitHub Issues - slightly more formal than Discord, but this is the system used for managing the project’s work, so if you create an issue, you can track its status
  • Email [email protected] - easy to use if you’re unfamiliar with Discord/GitHub

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

  • 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 issues have a narrow scope and are expected to entail a small number of changes, and ok first issues have a narrow scope, but are expected to be a bit tougher. You can check out the backlog of all refined 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.

Running the project

Make sure you have git and npm installed.

Clone & install dependencies:

git clone https://github.com/amelioro/ameliorate.git
cd ameliorate
npm install # repo-wide dependencies
npx husky install # activate commit hooks
cd web
npm install # project-specific dependencies

(see Commit hooks section for explanation of commit hooks)

Serve web project on localhost:

npm run dev # from web/

Codebase overview

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:

  • The directory structure mostly follows the guidance in this blog post for using modules for a nextjs project, except this is planned to be a mono-repo, so the root contains configs that are expected to be used across projects, and the rest currently lives in web/.
  • zustand: see docs/state-management.md
  • emotion: styled components are stored in co-located .styles.tsx files

Working with the code

Generally, the recommended setup is VS Code from the repo's root directory, with a terminal open in the web/ directory.

Most IDE-related settings are configured for working with vscode from the repo's root directory - known settings that might be problematic if not using vscode in the root directory: eslint, vscode eslint config, vscode tasks.

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 # from web/

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.

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.