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": "https://gitlab.com/Avris/FontAwesomePro",
```

with

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

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

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
# 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
```

Particular locales will be available under `http://<locale>.localhost:3000/`, eg. `http://en.localhost:3000/` for English.

### Building a development server bundle

If you need to build a server bundle you can run without having to use the Nuxt dev server, set `APP_ENV` to `development` when running `pnpm build`. This will keep any development-specific features enabled.

```sh
# Build a development server bundle.
APP_ENV=development pnpm build

# Start the server.
APP_ENV=development ./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 Vitest 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/generate.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

#### Unit tests

We currently have Vitest 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.

#### Snapshot smoke tests

We have a simple smoke test which sets up a [Docker](https://docker.com) container with a fresh database and runs the server. It then takes a snapshot of all available routes while signed in as an admin user. This is particularly useful when making moderate to major changes to the codebase when no changes in markup is expected.

To see command usage, run:

```sh
test/smoketest.sh --help
```

Typically, you would run the tests on a version of the code without your changes first to generate the snapshots, then run the tests again with your changes to compare the snapshots. If the snapshots are different, you can review the changes and decide if they are expected or not.

```sh
# Check out the target branch, e.g. main
git checkout main

# Generate snapshots for the German and English locales
test/smoketest.sh -u de en

# Check out your source branch
git checkout my-branch

# Run the tests again to compare the snapshots
test/smoketest.sh de en

# Any errors? Review the changes and decide if they are expected
test/smoketest.sh diff
```

##### Docker?

By running the application in Docker, we can:

- Run the tests in an isolated environment that does not change its behaviour depending on who runs it and how their computer is set up.
- Allow everyone to run the tests easily without having to worry about setting up any specific system dependencies for [Playwright](https://playwright.dev/).
- Run tests for multiple locales at once, since right now each locale requires building the application separately.
- Run tests in a controlled environment, where the database is always in the exact state we expect it to be in.
- Because of all of the above, allow multiple people to be able to reference the same deterministic snapshots when reviewing changes, knowing everyone will see the same markup.

You can technically run the tests without Docker. However, it is **not recommended**, as it is both slower with multiple locales and you lose all of the above benefits.

Doing so will run the tests against your current database, which means that data in your database may affect output in the snapshots and you are no longer guaranteed to have the same output as others. You also must be running an OS and distribution that is supported by Playwright, and it will install a number of dependencies directly on your system.

When running `pnpm test`, the snapshot tests will only run if `RUN_SNAPSHOT_TESTS` is set in your environment. The test suite will build all locales and run the tests for each locale in sequence. If running the tests manually, you can specify the locales you want to test by setting the `TEST_LOCALES` environment variable.

```sh
# Run the snapshot tests for all locales
RUN_SNAPSHOT_TESTS=true pnpm test -- --no-watch test/snapshot.test.ts

# Run the snapshot tests for only the Polish and Nynorsk locales
RUN_SNAPSHOT_TESTS=true TEST_LOCALES="pl nn" pnpm test -- --no-watch test/snapshot.test.ts
```

### 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)
- Check that it works both when navigating client-side and when using SSR
- 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

### Known pitfalls

- When using `$fetch` inside `useAsyncData`, remember that the original URL is not passed, 
  which prevents the locale-detection by locale. In such cases you need to manually provide the `locale` via a query.

### Integrations

#### Redis

Redis is used to store sessions and caches in production.
To run it locally, start the container in `docker/docker-compose.yml':

```bash
$ cd docker
$ docker compose up
```

If you need to inspect redis via `redis-cli` you can use:

```bash
$ docker compose run --interactive --tty --rm redis redis-cli -h redis
```

#### 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
# when using the filesystem
$ rm -rf .nuxt/cache
# when using redis
$ cd docker
$ docker compose exec redis sh -c "redis-cli KEYS \"cache:*\" | xargs -n 100 redis-cli DEL"
```

#### 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
- Faroese - @Sigmundur
- [Add yours!]