Update the contributing guidelines

Author: sandhose

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 <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.

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
-
-Copyright (C) 2004, 2006 The Linux Foundation and its contributors.
-660 York Street, Suite 102,
-San Francisco, CA 94110 USA
+There are two main ways to contribute to MAS:
 
-Everyone is permitted to copy and distribute verbatim copies of this
-license document, but changing it is not allowed.
+- **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).
 
-Developer's Certificate of Origin 1.1
+## 3. What do I need?
 
-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
+To get MAS running locally from source you will need:
 
-(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
+- [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)
 
-(c) The contribution was provided directly to me by some other
-    person who certified (a), (b) or (c) and I have not modified
-    it.
+## 4. Get the source
 
-(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.
-```
+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.
 
-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:
+Please base your changes on the `main` branch.
 
-```
-Signed-off-by: Your Name <your@email.example.org>
+```sh
+git clone git@github.com:YOUR_GITHUB_USER_NAME/matrix-authentication-service.git
+cd matrix-authentication-service
+git checkout main
 ```
 
-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.
+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.
 
-# 2. 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)
-
-# 3. Get the source
-
-- Clone this repository
-
-# 4. Build and run MAS
+## 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 <http://localhost:8080/>
 
-# 5. Learn about MAS
+## 6. Update generated files and format your code
+
+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).
 
-You can learn about the [architecture](architecture.md) and [database](database.md) of MAS here.
+Once both the CI and the developers are happy, the patch will be merged into Matrix Authentication Service and released shortly!

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