Zaimki.pl / Pronouns.page

Dependencies

• NodeJS version 20.12.2
• pnpm 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.

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

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

# Start the server.
APP_ENV=development ./run-wrapper.sh start

Copyright

See LICENSE.

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.

// ...
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

git config blame.ignoreRevsFile .git-blame-ignore-revs

Devtools

Nuxt Devtools 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 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 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:

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.

# 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.
• 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.

# 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.
Make sure that the .editorconfig looks like this:

[*.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':

$ cd docker
$ docker compose up

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

$ 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 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:

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

  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 first.
When you add a new language, remember to modify the file ./locale/locales.ts to add your language:

// 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!]