PronounsPage/README.md

# Zaimki.pl / Pronouns.page

## Dependencies

- [NodeJS](https://nodejs.org/en) version 20.12.2
- [pnpm](https://pnpm.io/installation) or other package manager

## Installation

```
git clone git@gitlab.com:PronounsPage/PronounsPage.git
```

We're using FontAwesome Pro, so to set up a local copy without having a FA license,
open `package.json` and replace

```
"@fortawesome/fontawesome-pro": "git+ssh://git@gitlab.com:Avris/FontAwesomePro.git",
```

with

```
"@fortawesome/fontawesome-pro": "git+ssh://git@gitlab.com:Avris/FakeFontAwesomePro.git",
```
or, for Git via HTTPS:

```
"@fortawesome/fontawesome-pro": "git+https://git@gitlab.com/Avris/FakeFontAwesomePro.git",
```

Do not commit that change!

## Build Setup

The steps below can also be done in Windows Subsystem for Linux. Just make sure it's WSL v2 or later.

```bash
# choose language version
$ make switch LANG=pl

# install dependencies
$ make install

# configure environment
$ nano .env

# run unit tests
$ make test

# serve with hot reload at localhost:3000
$ make run

# build for production and launch server
$ make deploy
$ ./run-wrapper.sh start
```

## Copyright

See [LICENSE](./LICENSE.md).

## Development Documentation

### User profiles

In order to test the login system, you can type in an email followed by a + (example@pronouns.page+). This way, you won't need a mailer, as the code will always be 999999. This feature is exclusive to development builds.

If you need an admin user in the development server, you can manually open the `db.sqlite` database
and give a user the `*` role in the `roles` column.

### Package manager

If you're having problems using pnpm, yarn or npm are probably fine,
but remember to switch any `pnpm [x]` commands for `yarn [x]` or `npm run [x]`.\
Remember to modify the `.env` file. You don't really need to set up any external APIs, just make up a secret.
```text
// ...
SECRET=replaceThis
// ...
```

### Editor

To work effectively with this project, it is recommended to configure these points in your editor:

- Integrating ESLint with auto-fixing on save (the formatting relies on it)
- Integrating Jest to easily view test results
- Use `yaml` syntax highlighting for `.suml` files
- Link `locale/config.schema.json` to `locale/*/config.suml` for schema validation and type hints
  (the schema file is automatically generated by `locale/generateSchemas.ts` in `make install`)

### Git

To exclude large formatting commits, add the ignore file to your config via
```bash
git config blame.ignoreRevsFile .git-blame-ignore-revs
```

### Devtools

[Nuxt Devtools](https://devtools.nuxt.com/) are enabled by default so you can access a toolbox directly in the browser.
To open files directly in your favorite editor,
you can add `LAUNCH_EDITOR={editor}` (e.g. `webstorm`, `phpstorm`, …) to your `.env`.
Additionally, you can install [Vue Devtools](https://vuejs.org/guide/scaling-up/tooling.html#browser-devtools)
in your browser.

### Linting

The configured ESLint rules are most of the times the recommended presets, with some tweaks and formatting rules added.
If you encounter warnings, please try to fix them in new code, and make a sensible decision when touching old code.
If you encounter a rule you disagree on or think another would add benefit,
please make a remark in the MR / on Discord.

### Testing

We currently have Jest as a simple unit testing framework.
While we don’t require unit tests for new code, a well-designed test is greatly appreciated.
The coverage reports on the MR are only meant for information purposes, not as a call to cover lines at all costs.

### Pipelines

While as an Open Source project we don’t practice Continous Integration or Continous Delivery by the book,
we have a “CI/CD” pipeline to ensure that our tests are passing and the lints don’t produce errors or fixable warnings.
We use our VPS as a GitLab runner.
Deployment is done manually.

### Windows

Current setup depends on working symlinks, which means that an NTFS filesystem is unfortunately required for Windows at the moment.

If you encounter a `ParseError`, make sure the file is in `\n` (_Line Feed_) mode instead of `\r\n` (_Carriage Return Line Feed_).

If you want to automate the change, [try this](https://stackoverflow.com/a/50006730). \
Make sure that the `.editorconfig` looks like this:
```text
[*.suml]
end_of_line = lf
```

### Server Password

For unpublished locales and for the test server, a password is required to access the web interface.
If you're on our Discord, you can ask for it there (or just use `published: true` for local development).

### Review Checklist

A non-comprehensive list of things to look out during development and review:

- Meet accessibility criteria in frontend (contrasts at least AA)
- Be consistent with the design guidelines (at `/design`)
- Check frontend in both dark and light mode
- Check that changes work in a differently configured locale (especially for optionally configurable features)
- Add new translations to `_base/translations.suml` and if applicable add a condition to `missingTranslations.js`
- Consider backwards-compatibility (e.g. links to pronouns in their profile or mail signature shouldn’t break)
- If you changed code related to server scripts, check that they keep running –
  there are some non-exhaustive smoke tests in the pipeline

### Integrations

#### AWS

If you want to test with AWS, you can fill in all the `AWS_*` values with your own credentials in `.env.dist`.
For small changes, you can ask to have your branch deployed on a test server.

#### Emails

When using `NODE_ENV=development`, emails will be displayed in stdout without being sent.
It's not in an easily readable format, but for many cases good enough.
If you want to actually see the message in a mail client,
you need to specify `MAILER_TRANSPORT` to use any provider you want (on production SMTP via AWS is used).
Remember to also set `MAILER_OVERWRITE` to your own address
– this way you won't accidentally send anything out to random addresses.

### Sentry

To enable sentry, you have to set the corresponding environment variables.
Remember that releases will not be published for development builds,
so to test them, you have to build a production build (`make deploy` and `nuxt start`, both with `NODE_ENV=development`).

### Troubleshooting

#### Invalid caches after changing code
Due to how [caches in Nitro](https://nitro.build/guide/cache) work, they automatically invalidate during development
when their function changes. However, this heuristic does not cover other functions the cached function depends on.
You can manually clear caches:
```bash
rm -rf .nuxt/cache
```

#### Module did not self-register

If you encounter an error `Module did not self-register`, triggered by the `canvas` dependency,
restart the development server.

#### Out-of-Memory in Nuxt development mode
If you experience a `JavaScript heap out of memory` error, it may help to disable typechecking (you can still typecheck via your editor or `pnpm vue-ts`):
- add to `nuxt.config.ts`:
  ```js
  typescript: {
      typeCheck: false,
  },
  ```

## Translation

### Contributing to an existing language version

You can either translate on-site via the translation mode, which will get merged eventually by the team
or by directly editing the corresponding `translation.suml`.
If a locale does not have a value translated, those inside `_base/translation.suml` are used.
Please check `TODO` comments and translation values which have been copied, but not translated from `_base`.
If the original contains internal links, ensure that the route is also valid for your locale.
To check for missing translations, you can use the `admin/translations/missing` route.

### Creating a new language version

Read [this](https://en.pronouns.page/new-version) first. \
When you add a new language, remember to modify the file `./locale/locales.ts` to add your language:
```js
// Add an object according to the following format:
new LocaleDescription('xx', 'xx', 'https://xx.pronouns.page', false, 'x', 'xxx'),

// Setting 'published' to true means that the language was published onto the main site.
// For example:
new LocaleDescription('pt', 'Português', 'https://pt.pronouns.page', true, 'ã', 'romance'),
```

### Current translations being worked on
- Catalan - @peiprjs
- Hebrew - @ThatTransGirl
- [Add yours!]