Skip to content
This repository has been archived by the owner on Dec 11, 2024. It is now read-only.

Latest commit

 

History

History
65 lines (44 loc) · 4.49 KB

contributing.md

File metadata and controls

65 lines (44 loc) · 4.49 KB
Raw

Contributing

Tech Stack

These are the major technologies we are using. Familiarity with most of these will make it easier to contribute.

Languages: typescript

Build tools: npm, nx

Web client: react, tailwind

API server: node, nextjs, prisma, postgresql

Local Development

  1. Install Node.js 18 (this includes npm). If you need to maintain multiple node versions for other projects, consider using nvm.
  2. In a terminal run: npm i -g nx to make the nx command available in a terminal.
  3. In a terminal run: npm install to install all of the project's dependencies.
  4. Install and set up a new database and then return to this document.
  5. In separate terminals run commands: nx serve api and nx serve web. This will make the api server available on port 4300 and the web server available on 4200.
  6. To login as ADMIN, user and password should be platform_admin@example.com and asdf1234.

Lambda Functions

Optional - We only use lambda functions for the gloss import logic. You only need to set up your local environment to run these if you are working on that code.

See the Lambda Functions documentation for details.

Development Environment

  • We use bash and zsh as our main terminal. Other terminals may work as well, but haven't been tested.
  • In VSCode, the ESLint and Prettier extensions will help enforce consistent formatting and linting rules. You can set VSCode up to use prettier as the formatter when saving a file.
  • When you commit, your code will be automatically linted and formatted. Please address issues this process flags.
  • It may also be helpful to install pgadmin to manage your local postgres databases.

Your first contribution

  • Familiarize yourself with the documentation and codebase so that you understand what the expectations are.
  • Take a look at the project to get a sense of what things have been prioritized to be worked on.
  • If you have never contributed to an open source repository before, you may find this tutorial helpful.

Pull Requests

  • Use conventional commit as your PR name. The most common prefixes we use are feat:, refactor:, chore:, and docs:.
  • Please avoid putting too much into a single PR. Large PRs are more difficult to review and tend to create more merge conflicts.
  • Follow the PR template to speed up the review process.
  • PRs are squashed before they are merged, so your commit names within the PR can be whatever you'd like.
  • Let the reviewer resolve comments in subsequent reviews as confirmation of changes completed as asked for.

Dependencies

  • Confirm that a third party package is necessary. In some cases, it may be preferrable to write our own code so that we can maintain it.
  • Packages must be open source. Either permissive (MIT, Apache) or copy-left (GPL, LGPL).
  • Packages must be reliable. Generally it's better for a package to be popular and maintained, but in some cases popular packages or younger packages with active development can be used.
    • The package is widely used: check the number of downloads on npmjs.com, use npm trends to check popularity over time.
    • The package is maintained: check contributions, stars, and releases on GitHub, or check the quality of documentation
  • Prefer smaller packages or packages that can be tree shaken to remove the unused parts. This limits the bloat of our build.
  • Lock the version down in package.json to a specific minor and patch version. This ensures that everyone is using the same version of dependencies.

Feature Flags

  • Use a feature flag to hide new functionality in production until it is complete. This allows work to be delivered in smaller chunks that aren't ready for users to see.
  • Feature flags can be turned on using an environment variable or with the query string _f=feat1,feat2.
  • To add a flag, update packages/web/src/shared/featureFlags.ts to specify the environment variable and string to use in query parameters. Then you can use the helper isFeatureEnabled(flag: string) in components to conditionally render based on the state of the flag.