letro/letro-authentication-service
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases 1 Wiki Activity

Update the contributing guidelines

Browse Source
This commit is contained in:
Quentin Gliech
2025-06-11 15:57:12 +02:00
parent c64086f213
commit c41ec28aa6
3 changed files with 77 additions and 117 deletions
Download Patch File Download Diff File Expand all files Collapse all files

56
CONTRIBUTING.md
View File

@@ -2,60 +2,4 @@
Thank you for taking the time to contribute to Matrix! Thank you for taking the time to contribute to Matrix!
This is the repository for MAS (Matrix Authentication Service), an OAuth 2.0 and OpenID Provider server for Matrix.
Please see the [contributors' guide](https://element-hq.github.io/matrix-authentication-service/development/contributing.html) in our rendered documentation. Please see the [contributors' guide](https://element-hq.github.io/matrix-authentication-service/development/contributing.html) in our rendered documentation.
## Sign off
We ask that everybody who contributes to this project signs off their contributions, as explained below.
We follow a simple 'inbound=outbound' model for contributions: the act of submitting an 'inbound' contribution means that the contributor agrees to license their contribution under the same terms as the project's overall 'outbound' license - in our case, this is Apache Software License v2 (see [LICENSE](./LICENSE)).
In order to have a concrete record that your contribution is intentional and you agree to license it under the same terms as the project's license, we've adopted the same lightweight approach used by the [Linux Kernel](https://www.kernel.org/doc/html/latest/process/submitting-patches.html), [Docker](https://github.com/docker/docker/blob/master/CONTRIBUTING.md), and many other projects: the [Developer Certificate of Origin](https://developercertificate.org/) (DCO). This is a simple declaration that you wrote the contribution or otherwise have the right to contribute it to Matrix:
```
Developer Certificate of Origin
Version 1.1
Copyright (C) 2004, 2006 The Linux Foundation and its contributors.
660 York Street, Suite 102,
San Francisco, CA 94110 USA
Everyone is permitted to copy and distribute verbatim copies of this
license document, but changing it is not allowed.
Developer's Certificate of Origin 1.1
By making a contribution to this project, I certify that:
(a) The contribution was created in whole or in part by me and I
have the right to submit it under the open source license
indicated in the file; or
(b) The contribution is based upon previous work that, to the best
of my knowledge, is covered under an appropriate open source
license and I have the right under that license to submit that
work with modifications, whether created in whole or in part
by me, under the same open source license (unless I am
permitted to submit under a different license), as indicated
in the file; or
(c) The contribution was provided directly to me by some other
person who certified (a), (b) or (c) and I have not modified
it.
(d) I understand and agree that this project and the contribution
are public and that a record of the contribution (including all
personal information I submit with it, including my sign-off) is
maintained indefinitely and may be redistributed consistent with
this project or the open source license(s) involved.
```
If you agree to this for your contribution, then all that's needed is to include the line in your commit or pull request comment:
```
Signed-off-by: Your Name <your@email.example.org>
```
Git allows you to add this signoff automatically when using the `-s` flag to `git commit`, which uses the name and email set in your `user.name` and `user.email` git configs.

136
docs/development/contributing.md
View File

@@ -2,79 +2,48 @@
This document aims to get you started with contributing to the Matrix Authentication Service! This document aims to get you started with contributing to the Matrix Authentication Service!
# 1. Who can contribute to MAS? ## 1. Who can contribute to MAS?
We ask that everybody who contributes to this project signs off their contributions, as explained below. Everyone is welcome to contribute code to [Synapse](https://github.com/element-hq/matrix-authentication-service), provided that they are willing to license their contributions to Element under a [Contributor License Agreement](https://cla-assistant.io/element-hq/matrix-authentication-service) (CLA). This ensures that their contribution will be made available under an OSI-approved open-source license, currently Affero General Public License v3 (AGPLv3).
Everyone is welcome to contribute code to [matrix.org projects](https://github.com/matrix-org), provided that they are willing to license their contributions under the same license as the project itself. We follow a simple 'inbound=outbound' model for contributions: the act of submitting an 'inbound' contribution means that the contributor agrees to license the code under the same terms as the project's overall 'outbound' license - in our case, this is almost always Apache Software License v2 (see [LICENSE](https://github.com/matrix-org/matrix-authentication-service/blob/main/LICENSE)). Please see the [Element blog post](https://element.io/blog/synapse-now-lives-at-github-com-element-hq-synapse/) for the full rationale.
In order to have a concrete record that your contribution is intentional and you agree to license it under the same terms as the project's license, we've adopted the same lightweight approach used by the [Linux Kernel](https://www.kernel.org/doc/html/latest/process/submitting-patches.html), [Docker](https://github.com/docker/docker/blob/master/CONTRIBUTING.md), and many other projects: the [Developer Certificate of Origin](https://developercertificate.org/) (DCO). This is a simple declaration that you wrote the contribution or otherwise have the right to contribute it to Matrix: ## 2. What can I contribute?
``` There are two main ways to contribute to MAS:
Developer Certificate of Origin
Version 1.1
Copyright (C) 2004, 2006 The Linux Foundation and its contributors. - **Code and documentation**: You can contribute code to the Matrix Authentication Service and help improve its documentation by submitting pull requests to the [GitHub repository](https://github.com/element-hq/matrix-authentication-service).
660 York Street, Suite 102, - **Translations**: You can contribute translations to the Matrix Authentication Service through [Localazy](https://localazy.com/p/matrix-authentication-service).
San Francisco, CA 94110 USA
Everyone is permitted to copy and distribute verbatim copies of this ## 3. What do I need?
license document, but changing it is not allowed.
Developer's Certificate of Origin 1.1
By making a contribution to this project, I certify that:
(a) The contribution was created in whole or in part by me and I
have the right to submit it under the open source license
indicated in the file; or
(b) The contribution is based upon previous work that, to the best
of my knowledge, is covered under an appropriate open source
license and I have the right under that license to submit that
work with modifications, whether created in whole or in part
by me, under the same open source license (unless I am
permitted to submit under a different license), as indicated
in the file; or
(c) The contribution was provided directly to me by some other
person who certified (a), (b) or (c) and I have not modified
it.
(d) I understand and agree that this project and the contribution
are public and that a record of the contribution (including all
personal information I submit with it, including my sign-off) is
maintained indefinitely and may be redistributed consistent with
this project or the open source license(s) involved.
```
If you agree to this for your contribution, then all that's needed is to include the line in your commit or pull request comment:
```
Signed-off-by: Your Name <your@email.example.org>
```
Git allows you to add this signoff automatically when using the `-s` flag to `git commit`, which uses the name and email set in your `user.name` and `user.email` git configs.
# 2. What do I need?
To get MAS running locally from source you will need: To get MAS running locally from source you will need:
- [Install Rust and Cargo](https://www.rust-lang.org/learn/get-started) - [Install Rust and Cargo](https://www.rust-lang.org/learn/get-started). We recommend using the latest stable version of Rust.
- [Install Node.js and npm](https://nodejs.org/) - [Install Node.js and npm](https://nodejs.org/). We recommend using the latest LTS version of Node.js.
- [Install Open Policy Agent](https://www.openpolicyagent.org/docs/latest/#1-download-opa) - [Install Open Policy Agent](https://www.openpolicyagent.org/docs#1-download-opa)
# 3. Get the source ## 4. Get the source
- Clone this repository The preferred and easiest way to contribute changes is to fork the relevant project on GitHub and then [create a pull request]( https://help.github.com/articles/using-pull-requests/) to ask us to pull your changes into our repo.
# 4. Build and run MAS Please base your changes on the `main` branch.
```sh
git clone git@github.com:YOUR_GITHUB_USER_NAME/matrix-authentication-service.git
cd matrix-authentication-service
git checkout main
```
If you need help getting started with git, this is beyond the scope of the document, but you can find many good git tutorials on the web.
## 5. Build and run MAS
- Build the frontend - Build the frontend
```sh ```sh
cd frontend cd frontend
npm ci npm ci # Install the frontend dependencies
npm run build npm run build # Build the frontend
cd .. cd ..
``` ```
- Build the Open Policy Agent policies - Build the Open Policy Agent policies
@@ -91,10 +60,57 @@ To get MAS running locally from source you will need:
docker run -p 5432:5432 -e 'POSTGRES_USER=postgres' -e 'POSTGRES_PASSWORD=postgres' -e 'POSTGRES_DATABASE=postgres' postgres docker run -p 5432:5432 -e 'POSTGRES_USER=postgres' -e 'POSTGRES_PASSWORD=postgres' -e 'POSTGRES_DATABASE=postgres' postgres
``` ```
- Update the database URI in `config.yaml` to `postgresql://postgres:postgres@localhost/postgres` - Update the database URI in `config.yaml` to `postgresql://postgres:postgres@localhost/postgres`
- Run the database migrations via `cargo run -- database migrate`
- Run the server via `cargo run -- server -c config.yaml` - Run the server via `cargo run -- server -c config.yaml`
- Go to <http://localhost:8080/> - Go to <http://localhost:8080/>
# 5. Learn about MAS ## 6. Update generated files and format your code
You can learn about the [architecture](architecture.md) and [database](database.md) of MAS here. The project includes a few files that are automatically generated.
Most of them can be updated by running `sh misc/update.sh` at the root of the project.
Make sure your code adheres to our Rust and TypeScript code style by running:
- `cargo +nightly fmt` (with the nightly toolchain installed)
- `npm run format` in the `frontend` directory
When updating SQL queries in the `crates/storage-pg/` crate, you may need to update the `sqlx` introspection data. To do this, make sure to install `cargo-sqlx` (`cargo install sqlx-cli`) and:
- Apply the latest migrations: `cargo sqlx migrate run` from the `crates/storage-pg/` directory.
- Update the `sqlx` introspection data: `cargo sqlx prepare` from the `crates/storage-pg/` directory.
## 7. Test, test, test!
While you're developing and before submitting a patch, you'll want to test your code and adhere to many code style and linting guidelines.
### Run the linters
- Run `cargo clippy --workspace` to lint the Rust code.
- Run `npm run lint` in the `frontend` directory to lint the frontend code.
### Run the tests
- Run the tests to the backend by running `cargo test --workspace`. This requires a connection to a PostgreSQL database, set via the `DATABASE_URL` environment variable.
- Run the tests to the frontend by running `npm run test` in the `frontend` directory.
## 8. Submit a pull request
Once you've made changes, you're ready to submit a pull request.
When the pull request is opened, you will see a few things:
1. Our automated CI (Continuous Integration) pipeline will run (again) the linters, the unit tests, the integration tests, and more.
1. One or more of the developers will take a look at your pull request and offer feedback.
From this point, you should:
1. Look at the results of the CI pipeline.
- If there is any error, fix the error.
1. If a developer has requested changes, make these changes and let us know when it is ready for a developer to review again.
- A pull request is a conversation; if you disagree with the suggestions, please respond and discuss it.
1. Create a new commit with the changes.
- Please do *not* overwrite the history. New commits make the reviewer's life easier.
- Push these commits to your pull request.
1. Back to 1.
1. Once the pull request is ready for review again, please **re-request review** from whichever developer did your initial review (or leave a comment in the pull request that you believe all required changes have been made).
Once both the CI and the developers are happy, the patch will be merged into Matrix Authentication Service and released shortly!

2
frontend/package.json
View File

@@ -5,7 +5,7 @@
"type": "module", "type": "module",
"scripts": { "scripts": {
"dev": "vite", "dev": "vite",
"generate": "graphql-codegen", "generate": "graphql-codegen && i18next",
"lint": "graphql-codegen && biome check && tsc && i18next --fail-on-warnings --fail-on-update", "lint": "graphql-codegen && biome check && tsc && i18next --fail-on-warnings --fail-on-update",
"format": "biome format --write", "format": "biome format --write",
"build": "rimraf ./dist/ && vite build", "build": "rimraf ./dist/ && vite build",