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

# 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
$ nuxt 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 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

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.

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.
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)
• 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 those scripts, check that they keep running:
  • server/analyseLinks.js
  • server/calendar.js
  • server/calendarBot.js (with arguments en,pl,es,pt,de,nl,fr,ja,ru,sv,lad,ua,vi twitter,mastodon)
  • server/cards.js
  • server/cleanupAccounts.js
  • server/cleanupImages.js
  • server/miastamaszerujace.js (pl locale only)
  • server/migrate.ts
  • server/notify.js
  • server/stats.ts
  • server/subscriptions.js

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

Hot Module Replacement in Nuxt development mode

If you're having issues with HMR not reloading automatically:

• The modules within package.json are matching the repo's package.json.
• nuxt.config.ts has the following option:

  watchers: {
      webpack: {
          aggregateTimeout: 300,
          poll: 1000
      }
  }
  

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
• [Add yours!]