mirror of
https://gitlab.com/PronounsPage/PronounsPage.git
synced 2025-09-24 05:05:20 -04:00
(doc) update contribution info
This commit is contained in:
Valentyne Stigloher
parent
20886dd79a
commit
89ce8c05eb
126
README.md
126
README.md
@ -1,5 +1,10 @@
|
||||
# Zaimki.pl / Pronouns.page
|
||||
|
||||
## Dependencies
|
||||
|
||||
- [NodeJS](https://nodejs.org/en)
|
||||
- [Yarn](https://yarnpkg.com/getting-started/install) or other package manager
|
||||
|
||||
## Installation
|
||||
|
||||
```
|
||||
@ -52,18 +57,16 @@ $ nuxt start
|
||||
See [LICENSE](./LICENSE.md).
|
||||
|
||||
## Development Documentation
|
||||
Read [this](https://en.pronouns.page/new-version) first. \
|
||||
When you add a new language, remember to modify the file `./locale/locales.js` to add your language:
|
||||
```js
|
||||
|
||||
// Add an object according to the following format:
|
||||
{code: 'xx', name: 'xx', url: 'https://xx.pronouns.page', published: false , symbol: 'x', family: 'xxx'}
|
||||
### User profiles
|
||||
|
||||
// Setting 'published' to true means that the language was published onto the main site.
|
||||
// For example:
|
||||
{code: 'pt', name: 'Português', url: 'https://pt.pronouns.page', published: true, symbol: 'ã', family: 'romance'}
|
||||
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 Yarn, npm is probably fine, but remember to switch any `yarn [x]` commands for `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
|
||||
@ -71,7 +74,40 @@ Remember to modify the `.env` file. You don't really need to set up any external
|
||||
SECRET=replaceThis
|
||||
// ...
|
||||
```
|
||||
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.
|
||||
|
||||
### Editor
|
||||
|
||||
Some libraries like Vue recommend using Visual Studio Code as editor.
|
||||
There are some recommended extensions in `.vscode/extensions.json` to help with development.
|
||||
When you want to use a different editor, you may need to configure some points to reduce manual work:
|
||||
|
||||
- Integrating ESLint with auto-fixing on save (the formatting relies on it)
|
||||
- Integration Jest to easily view test results
|
||||
- Use `yaml` syntax highlighting for `.suml` files
|
||||
|
||||
### Tools
|
||||
|
||||
For frontend development, check out the [Vue Devtools](https://vuejs.org/guide/scaling-up/tooling.html#browser-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
|
||||
|
||||
@ -85,26 +121,76 @@ Make sure that the `.editorconfig` looks like this:
|
||||
[*.suml]
|
||||
end_of_line = lf
|
||||
```
|
||||
### Password
|
||||
|
||||
### 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 to `expectedTranslations.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
|
||||
|
||||
By default, 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.
|
||||
|
||||
### Troubleshooting
|
||||
|
||||
If you're having issues with [HRM](https://webpack.js.org/concepts/hot-module-replacement/) (Hot Module Replacement) not reloading automatically:
|
||||
If you're having issues with [HRM](https://webpack.js.org/concepts/hot-module-replacement/) (Hot Module Replacement) not reloading automatically:
|
||||
- The modules within `package.json` are matching the repo's `package.json`.
|
||||
- `nuxt.config.js` has the following option:
|
||||
```js
|
||||
watchers: {
|
||||
webpack: {
|
||||
aggregateTimeout: 300,
|
||||
poll: 1000
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
## 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, not translated from `_base`.
|
||||
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.js` to add your language:
|
||||
```js
|
||||
watchers: {
|
||||
webpack: {
|
||||
aggregateTimeout: 300,
|
||||
poll: 1000
|
||||
}
|
||||
}
|
||||
// Add an object according to the following format:
|
||||
{ code: 'xx', name: 'xx', url: 'https://xx.pronouns.page', published: false, symbol: 'x', family: 'xxx' }
|
||||
|
||||
// Setting 'published' to true means that the language was published onto the main site.
|
||||
// For example:
|
||||
{ code: 'pt', name: 'Português', url: 'https://pt.pronouns.page', published: true, symbol: 'ã', family: 'romance' }
|
||||
```
|
||||
|
||||
## Current translations being worked on
|
||||
- Catalan - @peiprjs
|
||||
### Current translations being worked on
|
||||
- Catalan - @peiprjs
|
||||
- Hebrew - @ThatTransGirl
|
||||
- [Add yours!]
|
||||
|
||||
Loading…
x
Reference in New Issue
Block a user