Skip to content

Commit 6ba9823

Browse files
sandhosesandhose
authored
README, contribution and release documentation (#4675)
2 parents 7f16a9c + 2c8f8f3 commit 6ba9823

File tree

7 files changed

+216
-137
lines changed

7 files changed

+216
-137
lines changed

‎CONTRIBUTING.md

Lines changed: 0 additions & 56 deletions
Original file line numberDiff line numberDiff line change
@@ -2,60 +2,4 @@
22

33
Thank you for taking the time to contribute to Matrix!
44

5-
This is the repository for MAS (Matrix Authentication Service), an OAuth 2.0 and OpenID Provider server for Matrix.
6-
75
Please see the [contributors' guide](https://element-hq.github.io/matrix-authentication-service/development/contributing.html) in our rendered documentation.
8-
9-
## Sign off
10-
11-
We ask that everybody who contributes to this project signs off their contributions, as explained below.
12-
13-
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)).
14-
15-
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:
16-
17-
```
18-
Developer Certificate of Origin
19-
Version 1.1
20-
21-
Copyright (C) 2004, 2006 The Linux Foundation and its contributors.
22-
660 York Street, Suite 102,
23-
San Francisco, CA 94110 USA
24-
25-
Everyone is permitted to copy and distribute verbatim copies of this
26-
license document, but changing it is not allowed.
27-
28-
Developer's Certificate of Origin 1.1
29-
30-
By making a contribution to this project, I certify that:
31-
32-
(a) The contribution was created in whole or in part by me and I
33-
have the right to submit it under the open source license
34-
indicated in the file; or
35-
36-
(b) The contribution is based upon previous work that, to the best
37-
of my knowledge, is covered under an appropriate open source
38-
license and I have the right under that license to submit that
39-
work with modifications, whether created in whole or in part
40-
by me, under the same open source license (unless I am
41-
permitted to submit under a different license), as indicated
42-
in the file; or
43-
44-
(c) The contribution was provided directly to me by some other
45-
person who certified (a), (b) or (c) and I have not modified
46-
it.
47-
48-
(d) I understand and agree that this project and the contribution
49-
are public and that a record of the contribution (including all
50-
personal information I submit with it, including my sign-off) is
51-
maintained indefinitely and may be redistributed consistent with
52-
this project or the open source license(s) involved.
53-
```
54-
55-
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:
56-
57-
```
58-
Signed-off-by: Your Name <your@email.example.org>
59-
```
60-
61-
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.

‎README.md

Lines changed: 18 additions & 23 deletions
Original file line numberDiff line numberDiff line change
@@ -1,34 +1,29 @@
1-
# OAuth2.0 + OpenID Connect Provider for Matrix Homeservers
1+
# Matrix Authentication Service
22

3-
MAS (Matrix Authentication Service) is an OAuth 2.0 and OpenID Provider server for Matrix.
3+
MAS (Matrix Authentication Service) is a user management and authentication service for [Matrix](https://matrix.org/) homeservers, written and maintained by [Element](https://element.io/). You can directly run and manage the source code in this repository, available under an AGPL license (or alternatively under a commercial license from Element). Support is not provided by Element unless you have a subscription.
44

5-
It has been created to support the migration of Matrix to an OpenID Connect (OIDC) based authentication layer as per [MSC3861](https://github.com/matrix-org/matrix-doc/pull/3861).
5+
It has been created to support the migration of Matrix to a next-generation of auth APIs per [MSC3861](https://github.com/matrix-org/matrix-doc/pull/3861).
66

77
See the [Documentation](https://element-hq.github.io/matrix-authentication-service/index.html) for information on installation and use.
88

9-
You can learn more about Matrix and OIDC at [areweoidcyet.com](https://areweoidcyet.com/).
9+
You can learn more about Matrix and next-generation auth at [areweoidcyet.com](https://areweoidcyet.com/).
1010

11-
![Delegated OIDC architecture with MAS overview](overview.png)
11+
## 💬 Community room
1212

13-
## Features
13+
Developers and users of Matrix Authentication Service can chat in the [#matrix-auth:matrix.org](https://matrix.to/#/#matrix-auth:matrix.org) room on Matrix.
1414

15-
- Supported homeservers
16-
- ✅ Synapse
17-
- Authentication methods:
18-
- ✅ Upstream OIDC
19-
- 🚧 Local password
20-
- ‼️ [Application Services login](https://element-hq.github.io/matrix-authentication-service/as-login.html) (**Encrypted bridges**)
21-
- Migration support
22-
- ✅ Compatibility layer for legacy Matrix authentication
23-
- ✅ Advisor on migration readiness
24-
- ✅ Import users from Synapse
25-
- ✅ Import password hashes from Synapse
26-
- ✅ Import of external subject IDs for upstream identity providers from Synapse
15+
## 🛠️ Installing and configuration
2716

28-
## Upstream Identity Providers
17+
The best way to get a modern Element Matrix stack is through the [Element Server Suite Community Edition](https://github.com/element-hq/ess-helm), which includes MAS.
2918

30-
MAS is known to work with the following upstream IdPs via OIDC:
19+
The MAS documentation describes [how to install and configure MAS](https://element-hq.github.io/matrix-authentication-service/setup/).
20+
We recommend using the [Docker image](https://element-hq.github.io/matrix-authentication-service/setup/installation.html#using-the-docker-image) or the [pre-built binaries](https://element-hq.github.io/matrix-authentication-service/setup/installation.html#pre-built-binaries).
3121

32-
- [Keycloak](https://www.keycloak.org/)
33-
- [Dex](https://dexidp.io/)
34-
- [Google](https://developers.google.com/identity/openid-connect/openid-connect)
22+
## 📖 Translations
23+
24+
Matrix Authentication Service is available in multiple languages.
25+
Anyone can contribute to translations through [Localazy](https://localazy.com/element-matrix-authentication-service/).
26+
27+
## 🏗️ Contributing
28+
29+
See the [contribution guidelines](https://element-hq.github.io/matrix-authentication-service/contributing.html) for information on how to contribute to this project.

‎docs/SUMMARY.md

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -40,6 +40,7 @@
4040
# Development
4141

4242
- [Contributing](./development/contributing.md)
43+
- [Releasing](./development/releasing.md)
4344
- [Architecture](./development/architecture.md)
4445
- [Database](./development/database.md)
4546
- [Internal GraphQL API](./development/graphql.md)

‎docs/development/contributing.md

Lines changed: 73 additions & 57 deletions
Original file line numberDiff line numberDiff line change
@@ -2,79 +2,48 @@
22

33
This document aims to get you started with contributing to the Matrix Authentication Service!
44

5-
# 1. Who can contribute to MAS?
5+
## 1. Who can contribute to MAS?
66

7-
We ask that everybody who contributes to this project signs off their contributions, as explained below.
7+
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).
88

9-
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)).
9+
Please see the [Element blog post](https://element.io/blog/synapse-now-lives-at-github-com-element-hq-synapse/) for the full rationale.
1010

11-
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:
11+
## 2. What can I contribute?
1212

13-
```
14-
Developer Certificate of Origin
15-
Version 1.1
16-
17-
Copyright (C) 2004, 2006 The Linux Foundation and its contributors.
18-
660 York Street, Suite 102,
19-
San Francisco, CA 94110 USA
13+
There are two main ways to contribute to MAS:
2014

21-
Everyone is permitted to copy and distribute verbatim copies of this
22-
license document, but changing it is not allowed.
15+
- **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).
16+
- **Translations**: You can contribute translations to the Matrix Authentication Service through [Localazy](https://localazy.com/p/matrix-authentication-service).
2317

24-
Developer's Certificate of Origin 1.1
18+
## 3. What do I need?
2519

26-
By making a contribution to this project, I certify that:
20+
To get MAS running locally from source you will need to:
2721

28-
(a) The contribution was created in whole or in part by me and I
29-
have the right to submit it under the open source license
30-
indicated in the file; or
22+
- [Install Rust and Cargo](https://www.rust-lang.org/learn/get-started). We recommend using the latest stable version of Rust.
23+
- [Install Node.js and npm](https://nodejs.org/). We recommend using the latest LTS version of Node.js.
24+
- [Install Open Policy Agent](https://www.openpolicyagent.org/docs#1-download-opa)
3125

32-
(b) The contribution is based upon previous work that, to the best
33-
of my knowledge, is covered under an appropriate open source
34-
license and I have the right under that license to submit that
35-
work with modifications, whether created in whole or in part
36-
by me, under the same open source license (unless I am
37-
permitted to submit under a different license), as indicated
38-
in the file; or
26+
## 4. Get the source
3927

40-
(c) The contribution was provided directly to me by some other
41-
person who certified (a), (b) or (c) and I have not modified
42-
it.
43-
44-
(d) I understand and agree that this project and the contribution
45-
are public and that a record of the contribution (including all
46-
personal information I submit with it, including my sign-off) is
47-
maintained indefinitely and may be redistributed consistent with
48-
this project or the open source license(s) involved.
49-
```
28+
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.
5029

51-
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:
30+
Please base your changes on the `main` branch.
5231

32+
```sh
33+
git clone git@github.com:YOUR_GITHUB_USER_NAME/matrix-authentication-service.git
34+
cd matrix-authentication-service
35+
git checkout main
5336
```
54-
Signed-off-by: Your Name <your@email.example.org>
55-
```
56-
57-
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.
58-
59-
# 2. What do I need?
6037

61-
To get MAS running locally from source you will need:
38+
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.
6239

63-
- [Install Rust and Cargo](https://www.rust-lang.org/learn/get-started)
64-
- [Install Node.js and npm](https://nodejs.org/)
65-
- [Install Open Policy Agent](https://www.openpolicyagent.org/docs/latest/#1-download-opa)
66-
67-
# 3. Get the source
68-
69-
- Clone this repository
70-
71-
# 4. Build and run MAS
40+
## 5. Build and run MAS
7241

7342
- Build the frontend
7443
```sh
7544
cd frontend
76-
npm ci
77-
npm run build
45+
npm ci # Install the frontend dependencies
46+
npm run build # Build the frontend
7847
cd ..
7948
```
8049
- Build the Open Policy Agent policies
@@ -91,10 +60,57 @@ To get MAS running locally from source you will need:
9160
docker run -p 5432:5432 -e 'POSTGRES_USER=postgres' -e 'POSTGRES_PASSWORD=postgres' -e 'POSTGRES_DATABASE=postgres' postgres
9261
```
9362
- Update the database URI in `config.yaml` to `postgresql://postgres:postgres@localhost/postgres`
94-
- Run the database migrations via `cargo run -- database migrate`
9563
- Run the server via `cargo run -- server -c config.yaml`
9664
- Go to <http://localhost:8080/>
9765

98-
# 5. Learn about MAS
66+
## 6. Update generated files and format your code
67+
68+
The project includes a few files that are automatically generated.
69+
Most of them can be updated by running `sh misc/update.sh` at the root of the project.
70+
71+
Make sure your code adheres to our Rust and TypeScript code style by running:
72+
73+
- `cargo +nightly fmt` (with the nightly toolchain installed)
74+
- `npm run format` in the `frontend` directory
75+
76+
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:
77+
78+
- Apply the latest migrations: `cargo sqlx migrate run` from the `crates/storage-pg/` directory.
79+
- Update the `sqlx` introspection data: `cargo sqlx prepare` from the `crates/storage-pg/` directory.
80+
81+
## 7. Test, test, test!
82+
83+
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.
84+
85+
### Run the linters
86+
87+
- Run `cargo clippy --workspace` to lint the Rust code.
88+
- Run `npm run lint` in the `frontend` directory to lint the frontend code.
89+
90+
### Run the tests
91+
92+
- 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.
93+
- Run the tests to the frontend by running `npm run test` in the `frontend` directory.
94+
95+
## 8. Submit a pull request
96+
97+
Once you've made changes, you're ready to submit a pull request.
98+
99+
When the pull request is opened, you will see a few things:
100+
101+
1. Our automated CI (Continuous Integration) pipeline will run (again) the linters, the unit tests, the integration tests, and more.
102+
1. One or more of the developers will take a look at your pull request and offer feedback.
103+
104+
From this point, you should:
105+
106+
1. Look at the results of the CI pipeline.
107+
- If there is any error, fix the error.
108+
1. If a developer has requested changes, make these changes and let us know when it is ready for a developer to review again.
109+
- A pull request is a conversation; if you disagree with the suggestions, please respond and discuss it.
110+
1. Create a new commit with the changes.
111+
- Please do *not* overwrite the history. New commits make the reviewer's life easier.
112+
- Push these commits to your pull request.
113+
1. Back to 1.
114+
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).
99115

100-
You can learn about the [architecture](architecture.md) and [database](database.md) of MAS here.
116+
Once both the CI and the developers are happy, the patch will be merged into Matrix Authentication Service and released shortly!

0 commit comments

Comments
 (0)