cannery/CONTRIBUTING.md

146 lines
7.1 KiB
Markdown
Raw Permalink Normal View History

2022-01-31 20:04:38 -05:00
# Contribution Guide
Thanks for contributing to Cannery! Please read over the style tips to help make
contributing to Cannery (hopefully) as great of an experience as you found it!
## Translations needed!
2022-02-08 00:48:32 -05:00
[![translation
status](https://weblate.bubbletea.dev/widgets/cannery/-/287x66-black.png)](https://weblate.bubbletea.dev/engage/cannery)
If you're multilingual, this project can use your translations! Visit
[weblate](https://weblate.bubbletea.dev/engage/cannery/) for more information.
## Style Tips
2022-01-31 20:04:38 -05:00
2022-02-10 00:32:12 -05:00
- In order to keep code concise and improve readability, please try to make your
functions as short as possible while keeping variable names descriptive! For
instance, use inline `do:` blocks for short functions and make your aliases as
short as possible without introducing ambiguity.
2022-01-31 20:04:38 -05:00
- I.e. since there's only one `Changeset` in the app, please alias
2022-01-31 23:45:00 -05:00
`Changeset.t(Type.t())` instead of using `Ecto.Changeset.t(Long.Type.t())`
2022-02-10 00:32:12 -05:00
- Use pipelines when possible. If only calling a single method, a pipeline isn't
strictly necessary but still encouraged for future modification.
2022-01-31 20:04:38 -05:00
- Please add typespecs to your functions! Even your private functions may be
used by others later down the line, and typespecs will be able to help
document your code just a little bit better, and improve the debugging
process.
- Typespec arguments can be named like `@spec function(arg_name :: type()) ::
return_type()`. Please use these for generic types, such as `map()` when the
input data isn't immediately obvious.
2022-02-07 23:58:29 -05:00
- Please define all typespecs for a function together in one place, instead of
2022-02-10 00:32:12 -05:00
each function header.
2022-01-31 20:04:38 -05:00
- When making new models, please take inspiration from the existing models in
regards to layout of sections, typespec design, and formatting.
- With Elixir convention, for methods that raise on error please name them like
`function_that_raises!()`, and functions that return a boolean like
`function_that_returns_boolean?()`. For other methods, it's encouraged to use
status tuples for other functions like `{:ok, result}` or `{:error,
reason_or_changeset}` instead of just returning `result` or `nil` for easy
pattern matching.
2022-02-10 00:32:12 -05:00
- Instead of using the `.` operator, try to use pattern matching instead,
especially for function headers. `.` in templates is fine to keep things
concise.
- Use `Enum` functions over comprehensions whenever possible for clarity.
However, comprehensions in templates are fine for legibility.
- When adding text, please use `gettext` macros to enable things to be
translated in the future. After adding `gettext` macros, run `mix format` in
order to add your new text strings to the files in `priv/gettext`.
2022-02-09 00:13:01 -05:00
- Existing domains: `"default"` (for anything general), `"prompts"`
(informational messages as a result of the user doing an action, i.e. in
flashes), `"actions"` (actions that the user can take), `"emails"`, and
`"errors"`. Using these domains accurately will let translators know which
2022-02-10 00:32:12 -05:00
translations are higher and lower priority. Thank you!
- Before submitting a PR, please make sure all tests are passing using `mix
test`.
2022-01-31 20:04:38 -05:00
And as always, thank you!
# Technical Information
2022-01-31 20:04:38 -05:00
- Created using the [Phoenix Framework](https://www.phoenixframework.org)
2022-02-10 00:32:12 -05:00
- User Registration/Sign in via
[`phx_gen_auth`](https://hexdocs.pm/phx_gen_auth/).
2022-01-31 20:04:38 -05:00
- `Dockerfile` and example `docker-compose.yml`
- Automatic migrations in `MIX_ENV=prod` or Docker image
2022-05-05 23:59:31 -04:00
- JS linting with [standard.js](https://standardjs.com)
2022-01-31 20:04:38 -05:00
2022-02-09 01:12:50 -05:00
## Docs
More information can be found in the documentation generated by `mix docs`.
These are located in the `/docs` folder, and are generated in HTML and ePub.
Check them out!
2022-01-31 20:04:38 -05:00
# Instructions
1. Clone the repo
1. Install the elixir and erlang binaries. I recommend using [asdf version
manager](https://asdf-vm.com/guide/getting-started.html#_1-install-dependencies),
which will use the `.tool-versions` file to install the correct versions of
Erlang, Elixir and npm for this project!
1. Run `mix deps.get` and `mix compile` to fetch all dependencies
2022-02-10 00:32:12 -05:00
1. Run `mix setup` to initialize your database. You can reset your database at
any time with `mix ecto.reset`.
1. Run migrations with `mix ecto.migrate` or rollback with `mix ecto.rollback`.
2022-01-31 20:04:38 -05:00
1. Run `mix phx.server` to start the development server.
# Configuration
For development, I recommend setting environment variables with
[direnv](https://direnv.net).
By default, Cannery will always bind to all external IPv4 and IPv6 addresses in
`dev` and `prod` mode, respectively. If you would like to use different values,
they will need to be overridden in `config/dev.exs` and `config/runtime.exs` for
`dev` and `prod` modes, respectively.
2022-01-31 20:04:38 -05:00
## `MIX_ENV=dev`
In `dev` mode, Cannery will listen for these environment variables at runtime.
2022-01-31 20:04:38 -05:00
- `HOST`: External url to generate links with. Set this especially if you're
behind a reverse proxy. Defaults to `localhost`. External URLs will always be
generated with `https://` and port `443`.
- `PORT`: Internal port to bind to. Defaults to `4000`.
2022-01-31 20:04:38 -05:00
- `DATABASE_URL`: Controls the database url to connect to. Defaults to
`ecto://postgres:postgres@localhost/cannery_dev`.
- `ECTO_IPV6`: Controls if Ecto should use IPv6 to connect to PostgreSQL.
Defaults to `false`.
- `POOL_SIZE`: Controls the pool size to use with PostgreSQL. Defaults to `10`.
2022-01-31 20:04:38 -05:00
- `REGISTRATION`: Controls if user sign-up should be invite only or set to public. Set to `public` to enable public registration. Defaults to `invite`.
2022-05-05 23:26:29 -04:00
- `LOCALE`: Sets a custom default locale. Defaults to `en_US`.
2022-04-24 20:20:07 -04:00
- Available options: `en_US`, `de`, and `fr`
## `MIX_ENV=test`
In `test` mode (or in the Docker container), Cannery will listen for the same environment variables as dev mode, but also include the following at runtime:
- `TEST_DATABASE_URL`: REPLACES `DATABASE_URL`. Controls the database url to
connect to. Defaults to `ecto://postgres:postgres@localhost/cannery_test`.
- `MIX_TEST_PARTITION`: Only used if `TEST_DATABASE_URL` is not specified.
Appended to the default database url if you would like to partition your test
databases. Defaults to not set.
2022-01-31 20:04:38 -05:00
## `MIX_ENV=prod`
In `prod` mode (or in the Docker container), Cannery will listen for the same environment variables as dev mode, but also include the following at runtime:
2022-01-31 20:04:38 -05:00
- `SECRET_KEY_BASE`: Secret key base used to sign cookies. Must be generated
with `docker run -it shibaobun/cannery mix phx.gen.secret` and set for server to start.
2022-02-08 19:59:23 -05:00
- `SMTP_HOST`: The url for your SMTP email provider. Must be set
- `SMTP_PORT`: The port for your SMTP relay. Defaults to `587`.
- `SMTP_USERNAME`: The username for your SMTP relay. Must be set!
- `SMTP_PASSWORD`: The password for your SMTP relay. Must be set!
- `SMTP_SSL`: Set to `true` to enable SSL for emails. Defaults to `false`.
- `EMAIL_FROM`: Sets the sender email in sent emails. Defaults to
`no-reply@HOST` where `HOST` was previously defined.
- `EMAIL_NAME`: Sets the sender name in sent emails. Defaults to "Cannery".
# Contributers
Thank you so much for your contributions!
- shibao (https://misskey.bubbletea.dev/@shibao)
2022-04-19 18:16:06 -04:00
- kaia (https://shitposter.club/users/kaia)
2022-04-24 20:19:20 -04:00
- duponin (https://udongein.xyz/users/duponin)