You cannot select more than 25 topics
Topics must start with a letter or number, can include dashes ('-') and can be up to 35 characters long.
199 lines
9.0 KiB
Markdown
199 lines
9.0 KiB
Markdown
---
|
|
title: Development Guide
|
|
icon: git-merge
|
|
summary: 'How to install Plume on your computer and make changes to the source code.
|
|
This guide also gives you tips for making debugging and testing easier.'
|
|
time: 30 minutes
|
|
---
|
|
|
|
Plume is mostly made in Rust. The back-end uses Rocket and Diesel. The front-end
|
|
is in Rust too, thanks to WebAssembly. The stylesheets are written in SCSS.
|
|
|
|
If you want to write some code but you don't really know where to start, you
|
|
can try to find [an issue that interests you](https://git.joinplu.me/Plume/Plume/issues) ([GitHub](https://github.com/Plume-org/Plume/issues)).
|
|
|
|
Then, fork Plume (if you didn't already do it), `git clone` your fork, and start a
|
|
new branch with `git checkout -b NAME-OF-THE-BRANCH`. You can now start to work on the
|
|
issue.
|
|
|
|
Once you have something working, do `git add FILES THAT YOU CHANGED` (or `git add .` to add them all),
|
|
and then `git commit`. Write a message explaining your changes, and do `git push origin NAME-OF-THE-BRANCH`
|
|
to upload your work to Gitea or GitHub. Open the URL that appears in the output of this last command to open
|
|
a pull request, that we will then review, and eventually merge.
|
|
|
|
## Installing the development environment
|
|
|
|
Please refer to the [installation guide](../../installation/). Choose to compile Plume
|
|
from source when asked. Instead of using `cargo install`, use `cargo run` which
|
|
starts a freshly compiled debugging version of Plume.
|
|
|
|
It is recommended to enable the `debug-mailer` feature, especially if you need
|
|
emails during development. You can do it by passing the `--feature debug-mailer`
|
|
flags to `cargo`. When enabled, mails will be logged to the standard output instead
|
|
of being sent for real.
|
|
|
|
## Migrations
|
|
|
|
Migrations are files than can be used to update the database schema (for instance to add a new field to a model).
|
|
To create new migrations you will need a tool called `diesel`, that can be installed with:
|
|
|
|
```bash
|
|
cargo install diesel_cli --no-default-features --features DATABASE --version '=1.3.0'
|
|
```
|
|
|
|
After that to create a migration, both for PostgreSQL and SQlite, you need to run these two commands:
|
|
|
|
```
|
|
MIGRATION_DIRECTORY=migrations/postgres diesel migration generate NAME
|
|
MIGRATION_DIRECTORY=migrations/sqlite diesel migration generate NAME
|
|
```
|
|
|
|
Where `NAME` is the name you want to give to your migration, in one "word", for instance `add_role_to_users`.
|
|
New files will be generated in `migrations/postgres` and `migrations/sqlite`, called `up.sql` and `down.sql`.
|
|
The former should run the actual migration, and the later undo it.
|
|
|
|
You can also run some Rust code in migrations, by writing it in comments starting with `#!`, and wrapped in a closure taking
|
|
a database connection and a path to the current directory. You can access the `plume-models` modules with the `super` module.
|
|
Here is an example:
|
|
|
|
```sql
|
|
--#!|conn: &Connection, path: &Path| {
|
|
--#! println!("Running a migration from {}", path);
|
|
--#! println!("The admin of this instance is @{}", Instance::get_local(conn).unwrap().main_admin(conn).unwrap().name());
|
|
--#! Ok(())
|
|
--#!}
|
|
|
|
```
|
|
|
|
If your function is too long, you can also put it in `plume-models`, and simply give it's full identifier in the comment:
|
|
|
|
```sql
|
|
--#! crate::migrations::functions::my_migration_function
|
|
```
|
|
|
|
To run migrations, you can use `plm migration run`. To cancel and re-run them, use `plm migration redo`.
|
|
|
|
## Testing the federation
|
|
|
|
To test the federation, you'll need to setup another database,
|
|
also owned by the "plume" user, but with a different name. Then, you'll need to setup
|
|
this instance too.
|
|
|
|
The easiest way to do it is probably to install `plm` and `plume` globally (as explained
|
|
[here](../../installation/with/source-code/)), but with the `--debug` flag to avoid long compilation
|
|
times. Then create a copy of your `.env` file in another directory, and change the `DATABASE_URL`
|
|
and `ROCKET_PORT` variables. Then copy the migration files in this new directory and run them.
|
|
|
|
```
|
|
plm migration run
|
|
```
|
|
|
|
Setup the new instance with `plm` [as explained here](../../installation/config/).
|
|
|
|
Now, all you need for your two instances to be able to communicate is a fake domain
|
|
name with HTTPS for each of them. The first step to have that on your local machine is
|
|
to edit your `/etc/hosts` file, to create two new aliases by adding the following lines.
|
|
|
|
```
|
|
127.0.0.1 plume01.localhost
|
|
127.0.0.1 plume02.localhost
|
|
```
|
|
|
|
Now, we need to create SSL certificates for each of these domains. We will use `mkcert`
|
|
for this purpose. Here are [the instructions to install it](https://github.com/FiloSottile/mkcert#installation).
|
|
Once you installed it, run.
|
|
|
|
```bash
|
|
mkcert -install
|
|
mkcert plume01.localhost
|
|
mkcert plume02.localhost
|
|
```
|
|
|
|
Finally, we need a reverse proxy to load these certificates and redirect to the correct Plume instance for each domain.
|
|
We will use Caddy here as it is really simple to configure, but if you are more at ease with something else you can also
|
|
use alternatives.
|
|
|
|
To install Caddy, please refer to [their website](https://caddyserver.com/docs/install). Then create
|
|
a file called `Caddyfile` in the same directory you ran `mkcert` and write this inside.
|
|
|
|
```
|
|
plume01.localhost {
|
|
reverse_proxy localhost:7878
|
|
tls plume01.localhost.pem plume01.localhost-key.pem
|
|
}
|
|
|
|
plume02.localhost {
|
|
reverse_proxy 127.0.0.1:8787
|
|
tls plume02.localhost.pem plume02.localhost-key.pem
|
|
}
|
|
```
|
|
|
|
Eventually replace the ports in the `proxy` blocks by the one of your two instances, and
|
|
then run `caddy`. You can now open your browser and load `https://plume01.localhost` and `https://plume02.localhost`.
|
|
|
|
## Running tests
|
|
|
|
To run tests, use `DATABASE_URL` for tests and run migration at first.
|
|
|
|
To run tests of `plume-models` use `RUST_TEST_THREADS=1`, otherwise tests are run
|
|
concurrently, which causes error because they all use the same database.
|
|
|
|
## Internationalization
|
|
|
|
To mark a string as translatable wrap it in the `i18n!` macro. The first argument
|
|
should be the catalog to load translations from (usually `ctx.1` in templates), the
|
|
second the string to translate. You can specify format arguments after a `;`.
|
|
|
|
If your string vary depending on the number of elements, provide the plural version
|
|
as the third arguments, and the number of element as the first format argument.
|
|
|
|
You can find example uses of this macro [here](https://git.joinplu.me/plume/gettext-macros#user-content-example).
|
|
|
|
There is no need to provide individual translations of `i18n!`-wrapped strings in pull requests.
|
|
The strings will be uploaded to a third-party web service and translated automatically as
|
|
a separate step.
|
|
|
|
### Adding a language
|
|
|
|
Managers of the Crowdin project may add new languages to the list of target languages.
|
|
But for these new languages to be visible in the interface as well, some changes need to be made to the code.
|
|
|
|
First of all, make sure that the corresponding `.po` file is present in `po/plume`, and in `po/plume-front`.
|
|
If it is not, ask someone who has access to the Crowdin API key (like a Crowdin manager or owner) to pull it with the Crowdin CLI tool.
|
|
|
|
To find a manager, look at the list [in the sidebar of this page](https://crowdin.com/project/plume).
|
|
These people are managers because they were involved enough in the project, and especially in the translation process.
|
|
If you want to become a manager on Crowdin too, ask us [on Matrix](https://matrix.to/#/#plume-blog:matrix.org).
|
|
|
|
Then, in `src/main.rs` and `plume-front/src/main.rs`, add the code corresponding to the language in the `init_i18n!` macro.
|
|
If you don't know the code for the language: it is the name of the `.po` file, without the extension.
|
|
Here is an exemple of [a Pull Request adding Persian](https://git.joinplu.me/Plume/Plume/pulls/782).
|
|
|
|
`cargo check` to make sure everything compiles, and you are good to go!
|
|
|
|
## Working with the front-end
|
|
|
|
When working with the front-end, we try limit our use of JavaScript as much as possible.
|
|
Actually, we are not even using JavaScript since our front-end also uses Rust thanks to WebAssembly.
|
|
But we want Plume to work with as little JavaScript as possible, since reading a post (Plume's first goal)
|
|
shouldn't require a lot of interactions with the page.
|
|
|
|
When editing SCSS files, it is good to know that they are compiled by `cargo` too. But `cargo` can be
|
|
a bit slow, since it recompiles all of Plume every time, not only the SCSS files. A workaround is to run
|
|
`cargo run` in the background, and use `cargo build` to compile your SCSS, then kill it before the end of
|
|
the build. To know when your SCSS have been compiled, wait for cargo to tell you it is compiling `plume(bin)`
|
|
and not `plume(build)` (next to the progress bar).
|
|
|
|
Also, templates are using the Ructe syntax, which is a mix of Rust and HTML. They are compiled to Rust
|
|
and embedded in Plume, which means you have to re-run `cargo` everytime you make a change to the templates.
|
|
|
|
## Code Style
|
|
|
|
For Rust, use the standard style. `rustfmt` can help you keeping your code clean.
|
|
|
|
For SCSS, the only rules are to use One True Brace Style and two spaces to indent code.
|
|
|
|
For JavaScript, we use [the JavaScript Standard Style](https://standardjs.com/).
|
|
|
|
For HTML/Ructe templates, we use HTML5 syntax.
|