From c41ec28aa671277c4aa1ce6c6736908a03385bac Mon Sep 17 00:00:00 2001 From: Quentin Gliech Date: Wed, 11 Jun 2025 15:57:12 +0200 Subject: [PATCH] Update the contributing guidelines --- CONTRIBUTING.md | 56 ------------- docs/development/contributing.md | 136 +++++++++++++++++-------------- frontend/package.json | 2 +- 3 files changed, 77 insertions(+), 117 deletions(-) diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index 34370fae2..356a702c7 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -2,60 +2,4 @@ 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. - -## 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 -``` - -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. diff --git a/docs/development/contributing.md b/docs/development/contributing.md index 39057cb36..da7548557 100644 --- a/docs/development/contributing.md +++ b/docs/development/contributing.md @@ -2,79 +2,48 @@ 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? -``` -Developer Certificate of Origin -Version 1.1 +There are two main ways to contribute to MAS: -Copyright (C) 2004, 2006 The Linux Foundation and its contributors. -660 York Street, Suite 102, -San Francisco, CA 94110 USA +- **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). +- **Translations**: You can contribute translations to the Matrix Authentication Service through [Localazy](https://localazy.com/p/matrix-authentication-service). -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 -``` - -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? +## 3. What do I need? To get MAS running locally from source you will need: -- [Install Rust and Cargo](https://www.rust-lang.org/learn/get-started) -- [Install Node.js and npm](https://nodejs.org/) -- [Install Open Policy Agent](https://www.openpolicyagent.org/docs/latest/#1-download-opa) +- [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/). We recommend using the latest LTS version of Node.js. +- [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 ```sh cd frontend - npm ci - npm run build + npm ci # Install the frontend dependencies + npm run build # Build the frontend cd .. ``` - 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 ``` - 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` - Go to -# 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! diff --git a/frontend/package.json b/frontend/package.json index 068803780..4773014bb 100644 --- a/frontend/package.json +++ b/frontend/package.json @@ -5,7 +5,7 @@ "type": "module", "scripts": { "dev": "vite", - "generate": "graphql-codegen", + "generate": "graphql-codegen && i18next", "lint": "graphql-codegen && biome check && tsc && i18next --fail-on-warnings --fail-on-update", "format": "biome format --write", "build": "rimraf ./dist/ && vite build",