style: format contributing guide
This commit is contained in:
parent
fb8db21593
commit
94f63e67ef
147
CONTRIBUTING.md
147
CONTRIBUTING.md
|
@ -12,11 +12,12 @@ Help us keep Appwrite open and inclusive. Please read and follow our [Code of Co
|
||||||
|
|
||||||
## Submit a Pull Request 🚀
|
## Submit a Pull Request 🚀
|
||||||
|
|
||||||
Branch naming convention is as following
|
Branch naming convention is as following
|
||||||
|
|
||||||
`TYPE-ISSUE_ID-DESCRIPTION`
|
`TYPE-ISSUE_ID-DESCRIPTION`
|
||||||
|
|
||||||
example:
|
example:
|
||||||
|
|
||||||
```
|
```
|
||||||
doc-548-submit-a-pull-request-section-to-contribution-guide
|
doc-548-submit-a-pull-request-section-to-contribution-guide
|
||||||
```
|
```
|
||||||
|
@ -29,48 +30,55 @@ When `TYPE` can be:
|
||||||
- **fix** - a bug fix
|
- **fix** - a bug fix
|
||||||
- **refactor** - code change that neither fixes a bug nor adds a feature
|
- **refactor** - code change that neither fixes a bug nor adds a feature
|
||||||
|
|
||||||
**All PRs must include a commit message with the changes description!**
|
**All PRs must include a commit message with the changes description!**
|
||||||
|
|
||||||
For the initial start, fork the project and use git clone command to download the repository to your computer. A standard procedure for working on an issue would be to:
|
For the initial start, fork the project and use git clone command to download the repository to your computer. A standard procedure for working on an issue would be to:
|
||||||
|
|
||||||
1. `git pull`, before creating a new branch, pull the changes from upstream. Your master needs to be up to date.
|
1. `git pull`, before creating a new branch, pull the changes from upstream. Your master needs to be up to date.
|
||||||
|
|
||||||
```
|
```
|
||||||
$ git pull
|
$ git pull
|
||||||
```
|
```
|
||||||
|
|
||||||
2. Create new branch from `master` like: `doc-548-submit-a-pull-request-section-to-contribution-guide`<br/>
|
2. Create new branch from `master` like: `doc-548-submit-a-pull-request-section-to-contribution-guide`<br/>
|
||||||
|
|
||||||
```
|
```
|
||||||
$ git checkout -b [name_of_your_new_branch]
|
$ git checkout -b [name_of_your_new_branch]
|
||||||
```
|
```
|
||||||
|
|
||||||
3. Work - commit - repeat ( be sure to be in your branch )
|
3. Work - commit - repeat ( be sure to be in your branch )
|
||||||
|
|
||||||
4. Before you push your changes, make sure your code follows the `PSR12` coding standards , which is the standard Appwrite follows currently.
|
4. Before you push your changes, make sure your code follows the `PSR12` coding standards , which is the standard Appwrite follows currently. You can easily do this by running the formatter.
|
||||||
You can easily do this by running the formatter.
|
|
||||||
```bash
|
```bash
|
||||||
./vendor/bin/phpcbf <your file path>
|
./vendor/bin/phpcbf <your file path>
|
||||||
```
|
```
|
||||||
This will format the code according to the `PSR12` coding standard.
|
|
||||||
|
|
||||||
Now, go a step further by running the linter by the following command to manually fix the issues the formatter wasn't able to fix.
|
Now, go a step further by running the linter by the following command to manually fix the issues the formatter wasn't able to fix.
|
||||||
|
|
||||||
```bash
|
```bash
|
||||||
./vendor/bin/phpcs <your file path>
|
./vendor/bin/phpcs <your file path>
|
||||||
```
|
```
|
||||||
|
|
||||||
This will give you a list of errors for you to rectify , if there is an instance you need more information on the errors being displayed you can pass in additional command line arguments. More list of available arguments can be found [here](https://github.com/squizlabs/PHP_CodeSniffer/wiki/Usage). A very useful command line argument is `--report=diff`. This will give you the expected changes by the linter for easy fixing of formatting issues.
|
This will give you a list of errors for you to rectify , if there is an instance you need more information on the errors being displayed you can pass in additional command line arguments. More list of available arguments can be found [here](https://github.com/squizlabs/PHP_CodeSniffer/wiki/Usage). A very useful command line argument is `--report=diff`. This will give you the expected changes by the linter for easy fixing of formatting issues.
|
||||||
|
|
||||||
```bash
|
```bash
|
||||||
./vendor/bin/phpcs --report=diff <your file path>
|
./vendor/bin/phpcs --report=diff <your file path>
|
||||||
```
|
```
|
||||||
|
|
||||||
5. Push changes to GitHub
|
5. Push changes to GitHub
|
||||||
|
|
||||||
```
|
```
|
||||||
$ git push origin [name_of_your_new_branch]
|
$ git push origin [name_of_your_new_branch]
|
||||||
```
|
```
|
||||||
6. Submit your changes for review
|
|
||||||
If you go to your repository on GitHub, you'll see a `Compare & pull request` button. Click on that button.
|
6. Submit your changes for review
|
||||||
7. Start a Pull Request
|
If you go to your repository on GitHub, you'll see a `Compare & pull request` button. Click on that button.
|
||||||
Now submit the pull request and click on `Create pull request`.
|
7. Start a Pull Request
|
||||||
8. Get a code review approval/reject
|
Now submit the pull request and click on `Create pull request`.
|
||||||
9. After approval, merge your PR
|
8. Get a code review approval/reject
|
||||||
10. GitHub will automatically delete the branch after the merge is done. (they can still be restored).
|
9. After approval, merge your PR
|
||||||
|
10. GitHub will automatically delete the branch after the merge is done. (they can still be restored).
|
||||||
|
|
||||||
## Setup From Source
|
## Setup From Source
|
||||||
|
|
||||||
|
@ -106,11 +114,12 @@ Appwrite uses an internal micro-framework called Litespeed.js to build simple UI
|
||||||
|
|
||||||
After finishing the installation process, you can start writing and editing code.
|
After finishing the installation process, you can start writing and editing code.
|
||||||
|
|
||||||
|
|
||||||
#### Advanced Topics
|
#### Advanced Topics
|
||||||
|
|
||||||
We love to create issues that are good for beginners and label them as `good first issue` or `hacktoberfest`, but some more advanced topics might require extra knowledge. Below is a list of links you can use to learn more about some of the more advance topics that will help you master the Appwrite codebase.
|
We love to create issues that are good for beginners and label them as `good first issue` or `hacktoberfest`, but some more advanced topics might require extra knowledge. Below is a list of links you can use to learn more about some of the more advance topics that will help you master the Appwrite codebase.
|
||||||
|
|
||||||
##### Tools and Libs
|
##### Tools and Libs
|
||||||
|
|
||||||
- [Docker](https://www.docker.com/get-started)
|
- [Docker](https://www.docker.com/get-started)
|
||||||
- [PHP FIG](https://www.php-fig.org/) - [PSR-12](https://www.php-fig.org/psr/psr-12/)
|
- [PHP FIG](https://www.php-fig.org/) - [PSR-12](https://www.php-fig.org/psr/psr-12/)
|
||||||
- [PHP Swoole](https://www.swoole.co.uk/)
|
- [PHP Swoole](https://www.swoole.co.uk/)
|
||||||
|
@ -118,6 +127,7 @@ We love to create issues that are good for beginners and label them as `good fir
|
||||||
Learn more at our [Technology Stack](#technology-stack) section.
|
Learn more at our [Technology Stack](#technology-stack) section.
|
||||||
|
|
||||||
##### Network and Protocols
|
##### Network and Protocols
|
||||||
|
|
||||||
- [OSI Model](https://en.wikipedia.org/wiki/OSI_model)
|
- [OSI Model](https://en.wikipedia.org/wiki/OSI_model)
|
||||||
- [TCP vs UDP](https://www.guru99.com/tcp-vs-udp-understanding-the-difference.html#:~:text=TCP%20is%20a%20connection%2Doriented,speed%20of%20UDP%20is%20faster&text=TCP%20does%20error%20checking%20and,but%20it%20discards%20erroneous%20packets.)
|
- [TCP vs UDP](https://www.guru99.com/tcp-vs-udp-understanding-the-difference.html#:~:text=TCP%20is%20a%20connection%2Doriented,speed%20of%20UDP%20is%20faster&text=TCP%20does%20error%20checking%20and,but%20it%20discards%20erroneous%20packets.)
|
||||||
- [HTTP](https://en.wikipedia.org/wiki/Hypertext_Transfer_Protocol)
|
- [HTTP](https://en.wikipedia.org/wiki/Hypertext_Transfer_Protocol)
|
||||||
|
@ -126,10 +136,12 @@ Learn more at our [Technology Stack](#technology-stack) section.
|
||||||
- [gRPC](https://en.wikipedia.org/wiki/GRPC)
|
- [gRPC](https://en.wikipedia.org/wiki/GRPC)
|
||||||
|
|
||||||
##### Architecture
|
##### Architecture
|
||||||
|
|
||||||
- [Microservices vs Monolithic](https://www.mulesoft.com/resources/api/microservices-vs-monolithic#:~:text=Microservices%20architecture%20vs%20monolithic%20architecture&text=A%20monolithic%20application%20is%20built%20as%20a%20single%20unit.&text=To%20make%20any%20alterations%20to,formally%20with%20business%2Doriented%20APIs.)
|
- [Microservices vs Monolithic](https://www.mulesoft.com/resources/api/microservices-vs-monolithic#:~:text=Microservices%20architecture%20vs%20monolithic%20architecture&text=A%20monolithic%20application%20is%20built%20as%20a%20single%20unit.&text=To%20make%20any%20alterations%20to,formally%20with%20business%2Doriented%20APIs.)
|
||||||
- [MVVM](https://en.wikipedia.org/wiki/Model%E2%80%93view%E2%80%93viewmodel) - Appwrite console architecture
|
- [MVVM](https://en.wikipedia.org/wiki/Model%E2%80%93view%E2%80%93viewmodel) - Appwrite console architecture
|
||||||
|
|
||||||
##### Security
|
##### Security
|
||||||
|
|
||||||
- [Appwrite Auth and ACL](https://github.com/appwrite/appwrite/blob/0.7.x/docs/specs/authentication.drawio.svg)
|
- [Appwrite Auth and ACL](https://github.com/appwrite/appwrite/blob/0.7.x/docs/specs/authentication.drawio.svg)
|
||||||
- [OAuth](https://en.wikipedia.org/wiki/OAuth)
|
- [OAuth](https://en.wikipedia.org/wiki/OAuth)
|
||||||
- [Encryption](https://medium.com/searchencrypt/what-is-encryption-how-does-it-work-e8f20e340537#:~:text=Encryption%20is%20a%20process%20that,%2C%20or%20decrypt%2C%20the%20information.)
|
- [Encryption](https://medium.com/searchencrypt/what-is-encryption-how-does-it-work-e8f20e340537#:~:text=Encryption%20is%20a%20process%20that,%2C%20or%20decrypt%2C%20the%20information.)
|
||||||
|
@ -140,8 +152,8 @@ Learn more at our [Technology Stack](#technology-stack) section.
|
||||||
Appwrite's current structure is a combination of both [Monolithic](https://en.wikipedia.org/wiki/Monolithic_application) and [Microservice](https://en.wikipedia.org/wiki/Microservices) architectures, but our final goal, as we grow, is to be using only microservices.
|
Appwrite's current structure is a combination of both [Monolithic](https://en.wikipedia.org/wiki/Monolithic_application) and [Microservice](https://en.wikipedia.org/wiki/Microservices) architectures, but our final goal, as we grow, is to be using only microservices.
|
||||||
|
|
||||||
---
|
---
|
||||||
![Appwrite](docs/specs/overview.drawio.svg)
|
|
||||||
---
|
## ![Appwrite](docs/specs/overview.drawio.svg)
|
||||||
|
|
||||||
### File Structure
|
### File Structure
|
||||||
|
|
||||||
|
@ -220,15 +232,15 @@ Appwrite stack is combined from a variety of open-source technologies and tools.
|
||||||
|
|
||||||
### Other Technologies
|
### Other Technologies
|
||||||
|
|
||||||
* Redis - for managing cache and in-memory data (currently, we do not use Redis for persistent data)
|
- Redis - for managing cache and in-memory data (currently, we do not use Redis for persistent data)
|
||||||
* MariaDB - for database storage and queries
|
- MariaDB - for database storage and queries
|
||||||
* InfluxDB - for managing stats and time-series based data
|
- InfluxDB - for managing stats and time-series based data
|
||||||
* Statsd - for sending data over UDP protocol (using Telegraf)
|
- Statsd - for sending data over UDP protocol (using Telegraf)
|
||||||
* ClamAV - for validating and scanning storage files
|
- ClamAV - for validating and scanning storage files
|
||||||
* Imagemagick - for manipulating and managing image media files.
|
- Imagemagick - for manipulating and managing image media files.
|
||||||
* Webp - for better compression of images on supporting clients
|
- Webp - for better compression of images on supporting clients
|
||||||
* SMTP - for sending email messages and alerts
|
- SMTP - for sending email messages and alerts
|
||||||
* Resque - for managing data queues and scheduled tasks over a Redis server
|
- Resque - for managing data queues and scheduled tasks over a Redis server
|
||||||
|
|
||||||
## Package Managers
|
## Package Managers
|
||||||
|
|
||||||
|
@ -252,14 +264,14 @@ We wish Appwrite will be as easy to set up and in a single, localhost, and easy
|
||||||
|
|
||||||
When contributing code, please take into account the following considerations:
|
When contributing code, please take into account the following considerations:
|
||||||
|
|
||||||
* Response Time
|
- Response Time
|
||||||
* Throughput
|
- Throughput
|
||||||
* Requests per Seconds
|
- Requests per Seconds
|
||||||
* Network Usage
|
- Network Usage
|
||||||
* Memory Usage
|
- Memory Usage
|
||||||
* Browser Rendering
|
- Browser Rendering
|
||||||
* Background Jobs
|
- Background Jobs
|
||||||
* Task Execution Time
|
- Task Execution Time
|
||||||
|
|
||||||
## Security & Privacy
|
## Security & Privacy
|
||||||
|
|
||||||
|
@ -296,6 +308,7 @@ Before running the command, make sure you have proper write permissions to the A
|
||||||
```bash
|
```bash
|
||||||
docker buildx build --platform linux/amd64,linux/arm64,linux/arm/v6,linux/arm/v7,linux/arm64/v8,linux/ppc64le,linux/s390x -t appwrite/appwrite:dev --push .
|
docker buildx build --platform linux/amd64,linux/arm64,linux/arm/v6,linux/arm/v7,linux/arm64/v8,linux/ppc64le,linux/s390x -t appwrite/appwrite:dev --push .
|
||||||
```
|
```
|
||||||
|
|
||||||
**Build Functions Runtimes**
|
**Build Functions Runtimes**
|
||||||
|
|
||||||
The Runtimes for all supported cloud functions (multicore builds) can be found at the [open-runtimes/open-runtimes](https://github.com/open-runtimes/open-runtimes) repository.
|
The Runtimes for all supported cloud functions (multicore builds) can be found at the [open-runtimes/open-runtimes](https://github.com/open-runtimes/open-runtimes) repository.
|
||||||
|
@ -315,11 +328,11 @@ For generating a new console SDK follow the next steps:
|
||||||
|
|
||||||
Things to remember when releasing SDKs
|
Things to remember when releasing SDKs
|
||||||
|
|
||||||
* Update the Changelogs in **docs/sdks** (right now only Dart and Flutter are using these)
|
- Update the Changelogs in **docs/sdks** (right now only Dart and Flutter are using these)
|
||||||
* Update **GETTING_STARTED.md** in **docs/sdks** for each SDKs if any changes in the related APIs in there
|
- Update **GETTING_STARTED.md** in **docs/sdks** for each SDKs if any changes in the related APIs in there
|
||||||
* Update SDK versions as required on **app/config/platforms.php**
|
- Update SDK versions as required on **app/config/platforms.php**
|
||||||
* Generate SDKs using the command `php app/cli.php sdks` and follow the instructions
|
- Generate SDKs using the command `php app/cli.php sdks` and follow the instructions
|
||||||
* Release new tags on GitHub repository for each SDKs
|
- Release new tags on GitHub repository for each SDKs
|
||||||
|
|
||||||
## Debug
|
## Debug
|
||||||
|
|
||||||
|
@ -331,13 +344,13 @@ First, you need to create an init file. Duplicate **dev/yasd_init.php.stub** fil
|
||||||
|
|
||||||
```json
|
```json
|
||||||
{
|
{
|
||||||
"name": "Listen for Xdebug",
|
"name": "Listen for Xdebug",
|
||||||
"type": "php",
|
"type": "php",
|
||||||
"request": "launch",
|
"request": "launch",
|
||||||
"port": 9005,
|
"port": 9005,
|
||||||
"pathMappings": {
|
"pathMappings": {
|
||||||
"/usr/src/code": "${workspaceRoot}"
|
"/usr/src/code": "${workspaceRoot}"
|
||||||
},
|
}
|
||||||
}
|
}
|
||||||
```
|
```
|
||||||
|
|
||||||
|
@ -370,57 +383,58 @@ To run end-2-end tests for a spcific service use:
|
||||||
```bash
|
```bash
|
||||||
docker-compose exec appwrite test /usr/src/code/tests/e2e/Services/[ServiceName]
|
docker-compose exec appwrite test /usr/src/code/tests/e2e/Services/[ServiceName]
|
||||||
```
|
```
|
||||||
|
|
||||||
## Benchmarking
|
## Benchmarking
|
||||||
|
|
||||||
You can use WRK Docker image to benchmark the server performance. Benchmarking is extremely useful when you want to compare how the server behaves before and after a change has been applied. Replace [APPWRITE_HOSTNAME_OR_IP] with your Appwrite server hostname or IP. Note that localhost is not accessible from inside the WRK container.
|
You can use WRK Docker image to benchmark the server performance. Benchmarking is extremely useful when you want to compare how the server behaves before and after a change has been applied. Replace [APPWRITE_HOSTNAME_OR_IP] with your Appwrite server hostname or IP. Note that localhost is not accessible from inside the WRK container.
|
||||||
|
|
||||||
```
|
```
|
||||||
Options:
|
Options:
|
||||||
-c, --connections <N> Connections to keep open
|
-c, --connections <N> Connections to keep open
|
||||||
-d, --duration <T> Duration of test
|
-d, --duration <T> Duration of test
|
||||||
-t, --threads <N> Number of threads to use
|
-t, --threads <N> Number of threads to use
|
||||||
|
|
||||||
-s, --script <S> Load Lua script file
|
-s, --script <S> Load Lua script file
|
||||||
-H, --header <H> Add header to request
|
-H, --header <H> Add header to request
|
||||||
--latency Print latency statistics
|
--latency Print latency statistics
|
||||||
--timeout <T> Socket/request timeout
|
--timeout <T> Socket/request timeout
|
||||||
-v, --version Print version details
|
-v, --version Print version details
|
||||||
```
|
```
|
||||||
|
|
||||||
```bash
|
```bash
|
||||||
docker run --rm skandyla/wrk -t3 -c100 -d30 https://[APPWRITE_HOSTNAME_OR_IP]
|
docker run --rm skandyla/wrk -t3 -c100 -d30 https://[APPWRITE_HOSTNAME_OR_IP]
|
||||||
```
|
```
|
||||||
|
|
||||||
## Code Maintenance
|
## Code Maintenance
|
||||||
|
|
||||||
We use some automation tools to help us keep a healthy codebase.
|
We use some automation tools to help us keep a healthy codebase.
|
||||||
|
|
||||||
Coding Standards:
|
Coding Standards:
|
||||||
|
|
||||||
`Run Formatter` :
|
**Run Formatter:**
|
||||||
|
|
||||||
```bash
|
```bash
|
||||||
./vendor/bin/phpcbf --standard=PSR12 <your file path>
|
./vendor/bin/phpcbf <your file path>
|
||||||
```
|
```
|
||||||
|
|
||||||
`Run Linter` :
|
**Run Linter:**
|
||||||
|
|
||||||
```bash
|
```bash
|
||||||
./vendor/bin/phpcs --standard=PSR12 <your file path>
|
./vendor/bin/phpcs <your file path>
|
||||||
```
|
```
|
||||||
|
|
||||||
## Tutorials
|
## Tutorials
|
||||||
|
|
||||||
From time to time, our team will add tutorials that will help contributors find their way in the Appwrite source code. Below is a list of currently available tutorials:
|
From time to time, our team will add tutorials that will help contributors find their way in the Appwrite source code. Below is a list of currently available tutorials:
|
||||||
|
|
||||||
* [Adding Support for a New OAuth2 Provider](./docs/tutorials/add-oauth2-provider.md)
|
- [Adding Support for a New OAuth2 Provider](./docs/tutorials/add-oauth2-provider.md)
|
||||||
* [Appwrite Environment Variables](./docs/tutorials/environment-variables.md)
|
- [Appwrite Environment Variables](./docs/tutorials/environment-variables.md)
|
||||||
* [Running in Production](./docs/tutorials/running-in-production.md)
|
- [Running in Production](./docs/tutorials/running-in-production.md)
|
||||||
* [Adding Storage Adapter](./docs/tutorials/add-storage-adapter.md)
|
- [Adding Storage Adapter](./docs/tutorials/add-storage-adapter.md)
|
||||||
|
|
||||||
## Other Ways to Help
|
## Other Ways to Help
|
||||||
|
|
||||||
Pull requests are great, but there are many other areas where you can help Appwrite.
|
Pull requests are great, but there are many other areas where you can help Appwrite.
|
||||||
|
|
||||||
### Blogging & Speaking
|
### Blogging & Speaking
|
||||||
|
|
||||||
|
@ -445,4 +459,3 @@ Submitting documentation updates, enhancements, designs, or bug fixes. Spelling
|
||||||
### Helping Someone
|
### Helping Someone
|
||||||
|
|
||||||
Searching for Appwrite on Discord, GitHub, or StackOverflow and helping someone else who needs help. You can also help by teaching others how to contribute to Appwrite's repo!
|
Searching for Appwrite on Discord, GitHub, or StackOverflow and helping someone else who needs help. You can also help by teaching others how to contribute to Appwrite's repo!
|
||||||
|
|
||||||
|
|
Loading…
Reference in a new issue