From 4a495f61d5af40cc832507707658654c082a2401 Mon Sep 17 00:00:00 2001 From: Steven Nguyen Date: Wed, 16 Nov 2022 10:47:21 -0800 Subject: [PATCH 1/9] Remove code of conduct in favor of the org level file --- CODE_OF_CONDUCT.md | 76 ---------------------------------------------- 1 file changed, 76 deletions(-) delete mode 100644 CODE_OF_CONDUCT.md diff --git a/CODE_OF_CONDUCT.md b/CODE_OF_CONDUCT.md deleted file mode 100644 index 5dba194a2b..0000000000 --- a/CODE_OF_CONDUCT.md +++ /dev/null @@ -1,76 +0,0 @@ -# Contributor Covenant Code of Conduct - -## Our Pledge - -In the interest of fostering an open and welcoming environment, we as -contributors and maintainers pledge to make participation in our project and -our community a harassment-free experience for everyone, regardless of age, body -size, disability, ethnicity, sex characteristics, gender identity, expression, -level of experience, education, socio-economic status, nationality, personal -appearance, race, religion, or sexual identity and orientation. - -## Our Standards - -Examples of behavior that contributes to creating a positive environment -include: - -* Using welcoming and inclusive language -* Being respectful of differing viewpoints and experiences -* Gracefully accepting constructive criticism -* Focusing on what is best for the community -* Showing empathy towards other community members - -Examples of unacceptable behavior by participants include: - -* The use of sexualized language or imagery and unwelcome sexual attention or - advances -* Trolling, insulting/derogatory comments, and personal or political attacks -* Public or private harassment -* Publishing others' private information, such as a physical or electronic - address, without explicit permission -* Other conduct which could reasonably be considered inappropriate in a - professional setting - -## Our Responsibilities - -Project maintainers are responsible for clarifying the standards of acceptable -behavior and are expected to take appropriate and fair corrective action in -response to any instances of unacceptable behavior. - -Project maintainers have the right and responsibility to remove, edit, or -reject comments, commits, code, wiki edits, issues, and other contributions -that are not aligned to this Code of Conduct, or to ban temporarily or -permanently any contributor for other behaviors that they deem inappropriate, -threatening, offensive, or harmful. - -## Scope - -This Code of Conduct applies both within project spaces and in public spaces -when an individual is representing the project or its community. Examples of -representing a project or community include using an official project e-mail -address, posting via an official social media account, or acting as an appointed -representative at an online or offline event. Representation of a project may be -further defined and clarified by project maintainers. - -## Enforcement - -Instances of abusive, harassing, or otherwise unacceptable behavior may be -reported by contacting the project team at team@appwrite.io. All -complaints will be reviewed and investigated and will result in a response that -is deemed necessary and appropriate to the circumstances. The project team is -obligated to maintain confidentiality with regard to the reporter of an incident. -Further details of specific enforcement policies may be posted separately. - -Project maintainers who do not follow or enforce the Code of Conduct in good -faith may face temporary or permanent repercussions as determined by other -members of the project's leadership. - -## Attribution - -This Code of Conduct is adapted from the [Contributor Covenant][homepage], version 1.4, -available at https://www.contributor-covenant.org/version/1/4/code-of-conduct.html - -[homepage]: https://www.contributor-covenant.org - -For answers to common questions about this code of conduct, see -https://www.contributor-covenant.org/faq From a309beddf5bc7acdf932e18d10314eb730fdf4f7 Mon Sep 17 00:00:00 2001 From: Steven Nguyen Date: Wed, 16 Nov 2022 10:50:12 -0800 Subject: [PATCH 2/9] Update supported versions --- SECURITY.md | 3 ++- 1 file changed, 2 insertions(+), 1 deletion(-) diff --git a/SECURITY.md b/SECURITY.md index d0e4c98f1b..a40ca1e3f9 100644 --- a/SECURITY.md +++ b/SECURITY.md @@ -5,8 +5,9 @@ | Version | Supported | | ------- | ------------------ | | <= 0.14 | :x: | -| 0.15.x | :white_check_mark: | +| 1.15.x | :white_check_mark: | | 1.0.x | :white_check_mark: | +| 1.1.x | :white_check_mark: | ## Reporting a Vulnerability From 2ede405784f92ad67ff5dbd622a84b36f31182cd Mon Sep 17 00:00:00 2001 From: Steven Nguyen Date: Wed, 16 Nov 2022 10:50:43 -0800 Subject: [PATCH 3/9] Remove issue templates in favor of org level files --- .github/ISSUE_TEMPLATE/bug.yaml | 88 ----------------------- .github/ISSUE_TEMPLATE/documentation.yaml | 32 --------- .github/ISSUE_TEMPLATE/feature.yaml | 40 ----------- 3 files changed, 160 deletions(-) delete mode 100644 .github/ISSUE_TEMPLATE/bug.yaml delete mode 100644 .github/ISSUE_TEMPLATE/documentation.yaml delete mode 100644 .github/ISSUE_TEMPLATE/feature.yaml diff --git a/.github/ISSUE_TEMPLATE/bug.yaml b/.github/ISSUE_TEMPLATE/bug.yaml deleted file mode 100644 index dbd8239d5b..0000000000 --- a/.github/ISSUE_TEMPLATE/bug.yaml +++ /dev/null @@ -1,88 +0,0 @@ -name: "๐Ÿ› Bug Report" -description: "Submit a bug report to help us improve" -title: "๐Ÿ› Bug Report: " -labels: [bug] -body: - - type: markdown - attributes: - value: | - Thanks for taking the time to fill out our bug report form ๐Ÿ™ - - type: textarea - id: steps-to-reproduce - validations: - required: true - attributes: - label: "๐Ÿ‘Ÿ Reproduction steps" - description: "How do you trigger this bug? Please walk us through it step by step." - placeholder: "When I ..." - - type: textarea - id: expected-behavior - validations: - required: true - attributes: - label: "๐Ÿ‘ Expected behavior" - description: "What did you think would happen?" - placeholder: "It should ..." - - type: textarea - id: actual-behavior - validations: - required: true - attributes: - label: "๐Ÿ‘Ž Actual Behavior" - description: "What did actually happen? Add screenshots, if applicable." - placeholder: "It actually ..." - - type: dropdown - id: appwrite-version - attributes: - label: "๐ŸŽฒ Appwrite version" - description: "What version of Appwrite are you running?" - options: - - Version 1.0.x - - Version 0.15.x - - Version 0.14.x - - Version 0.13.x - - Version 0.12.x - - Version 0.11.x - - Version 0.10.x - - Version 0.9.x - - Version 0.8.x - - Version 0.7.x - - Version 0.6.x - - Different version (specify in environment) - validations: - required: true - - type: dropdown - id: operating-system - attributes: - label: "๐Ÿ’ป Operating system" - description: "What OS is your server / device running on?" - options: - - Linux - - MacOS - - Windows - - Something else - validations: - required: true - - type: textarea - id: environment - validations: - required: false - attributes: - label: "๐Ÿงฑ Your Environment" - description: "Is your environment customized in any way?" - placeholder: "I use Cloudflare for ..." - - type: checkboxes - id: no-duplicate-issues - attributes: - label: "๐Ÿ‘€ Have you spent some time to check if this issue has been raised before?" - description: "Have you Googled for a similar issue or checked our older issues for a similar bug?" - options: - - label: "I checked and didn't find similar issue" - required: true - - type: checkboxes - id: read-code-of-conduct - attributes: - label: "๐Ÿข Have you read the Code of Conduct?" - options: - - label: "I have read the [Code of Conduct](https://github.com/appwrite/appwrite/blob/HEAD/CODE_OF_CONDUCT.md)" - required: true diff --git a/.github/ISSUE_TEMPLATE/documentation.yaml b/.github/ISSUE_TEMPLATE/documentation.yaml deleted file mode 100644 index c2f829df39..0000000000 --- a/.github/ISSUE_TEMPLATE/documentation.yaml +++ /dev/null @@ -1,32 +0,0 @@ -name: "๐Ÿ“š Documentation" -description: "Report an issue related to documentation" -title: "๐Ÿ“š Documentation: " -labels: [documentation] -body: - - type: markdown - attributes: - value: | - Thanks for taking the time to make our documentation better ๐Ÿ™ - - type: textarea - id: issue-description - validations: - required: true - attributes: - label: "๐Ÿ’ญ Description" - description: "A clear and concise description of what the issue is." - placeholder: "Documentation should not ..." - - type: checkboxes - id: no-duplicate-issues - attributes: - label: "๐Ÿ‘€ Have you spent some time to check if this issue has been raised before?" - description: "Have you Googled for a similar issue or checked our older issues for a similar bug?" - options: - - label: "I checked and didn't find similar issue" - required: true - - type: checkboxes - id: read-code-of-conduct - attributes: - label: "๐Ÿข Have you read the Code of Conduct?" - options: - - label: "I have read the [Code of Conduct](https://github.com/appwrite/appwrite/blob/HEAD/CODE_OF_CONDUCT.md)" - required: true \ No newline at end of file diff --git a/.github/ISSUE_TEMPLATE/feature.yaml b/.github/ISSUE_TEMPLATE/feature.yaml deleted file mode 100644 index 6181cda753..0000000000 --- a/.github/ISSUE_TEMPLATE/feature.yaml +++ /dev/null @@ -1,40 +0,0 @@ -name: ๐Ÿš€ Feature -description: "Submit a proposal for a new feature" -title: "๐Ÿš€ Feature: " -labels: [feature] -body: - - type: markdown - attributes: - value: | - Thanks for taking the time to fill out our feature request form ๐Ÿ™ - - type: textarea - id: feature-description - validations: - required: true - attributes: - label: "๐Ÿ”– Feature description" - description: "A clear and concise description of what the feature is." - placeholder: "You should add ..." - - type: textarea - id: pitch - validations: - required: true - attributes: - label: "๐ŸŽค Pitch" - description: "Please explain why this feature should be implemented and how it would be used. Add examples, if applicable." - placeholder: "In my use-case, ..." - - type: checkboxes - id: no-duplicate-issues - attributes: - label: "๐Ÿ‘€ Have you spent some time to check if this issue has been raised before?" - description: "Have you Googled for a similar issue or checked our older issues for a similar bug?" - options: - - label: "I checked and didn't find similar issue" - required: true - - type: checkboxes - id: read-code-of-conduct - attributes: - label: "๐Ÿข Have you read the Code of Conduct?" - options: - - label: "I have read the [Code of Conduct](https://github.com/appwrite/appwrite/blob/HEAD/CODE_OF_CONDUCT.md)" - required: true \ No newline at end of file From 3d01bf65050e0e24cc804491a186f7230470483d Mon Sep 17 00:00:00 2001 From: Steven Nguyen Date: Wed, 16 Nov 2022 20:37:24 -0800 Subject: [PATCH 4/9] Update links to code of conduct --- CONTRIBUTING.md | 2 +- docs/tutorials/add-environment-variable.md | 7 +- docs/tutorials/add-oauth2-provider.md | 10 ++- docs/tutorials/add-route.md | 82 ++++++++++++-------- docs/tutorials/add-runtime.md | 87 +++++++++++++++++----- docs/tutorials/add-storage-adapter.md | 14 +++- docs/tutorials/add-translations.md | 74 +++++++++--------- 7 files changed, 180 insertions(+), 96 deletions(-) diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index e579884037..773206f239 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -8,7 +8,7 @@ If you are worried or donโ€™t know where to start, check out our next section ex ## Code of Conduct -Help us keep Appwrite open and inclusive. Please read and follow our [Code of Conduct](/CODE_OF_CONDUCT.md). +Help us keep Appwrite open and inclusive. Please read and follow our [Code of Conduct](/https://github.com/appwrite/.github/blob/main/CODE_OF_CONDUCT.md). ## Submit a Pull Request ๐Ÿš€ diff --git a/docs/tutorials/add-environment-variable.md b/docs/tutorials/add-environment-variable.md index e4bbb78454..f5df1e69c4 100644 --- a/docs/tutorials/add-environment-variable.md +++ b/docs/tutorials/add-environment-variable.md @@ -1,26 +1,31 @@ # Introducing new Environment Variable -This document is part of the Appwrite contributors' guide. Before you continue reading this document, make sure you have read the [Code of Conduct](https://github.com/appwrite/appwrite/blob/master/CODE_OF_CONDUCT.md) and the [Contributing Guide](https://github.com/appwrite/appwrite/blob/master/CONTRIBUTING.md). +This document is part of the Appwrite contributors' guide. Before you continue reading this document, make sure you have read the [Code of Conduct](https://github.com/appwrite/.github/blob/main/CODE_OF_CONDUCT.md) and the [Contributing Guide](https://github.com/appwrite/appwrite/blob/master/CONTRIBUTING.md). ## Getting Started ### Agenda + Adding new features may require various configuration options to be set by the users. And for such options, we use environment variables in Appwrite. This tutorial will cover how to properly add a new environment variable in Appwrite. ### Naming environment variable + The environment variables in Appwrite are prefixed with `_APP_`. If it belongs to a specific category, the category name is appended as `_APP_REDIS` for the Redis category. The available categories are General, Redis, MariaDB, InfluxDB, StatsD, SMTP, Storage, Functions and Maintenance. Finally, a properly describing name is given to the variable. For example, `_APP_REDIS_HOST` is an environment variable for the hostname of your Redis instance. You can find more information on available categories and existing environment variables in the [environment variables doc](https://appwrite.io/docs/environment-variables). ### Describe new environment variable + First of all, we add the new environment variable to `app/config/variables.php` in the designated category. If none of the categories fit, add it to the General category. Copy the existing variable description to create a new one so that you will not miss any required fields. This information is also used to generate the website documentation at https://appwrite.io/docs/environment-variables, so please use good descriptions that clearly define the purpose and other required info about the environment variable that you are adding. ### Add to .env and Dockerfile + If the newly introduced environment variable has a default value, add it to the `.env` and `Dockerfile` along with other environment variables. `.env` file uses settings for Appwrite development environment. ### Add to Docker Compose file and template + Add the new environment variables to the `docker-compose.yml` and `app/views/install/compose.phtml` for each docker service that requires access to those environment variables. The `docker-compose.yml` file is used by the Appwrite maintainers during development, whereas the `app/views/install/compose.phtml` file is used by the Appwrite setup script. diff --git a/docs/tutorials/add-oauth2-provider.md b/docs/tutorials/add-oauth2-provider.md index e1f605fcf5..4aa20649ca 100644 --- a/docs/tutorials/add-oauth2-provider.md +++ b/docs/tutorials/add-oauth2-provider.md @@ -1,6 +1,6 @@ # Adding a new OAuth2 provider ๐Ÿ›ก -This document is part of the Appwrite contributors' guide. Before you continue reading this document make sure you have read the [Code of Conduct](https://github.com/appwrite/appwrite/blob/master/CODE_OF_CONDUCT.md) and the [Contributing Guide](https://github.com/appwrite/appwrite/blob/master/CONTRIBUTING.md). +This document is part of the Appwrite contributors' guide. Before you continue reading this document make sure you have read the [Code of Conduct](https://github.com/appwrite/.github/blob/main/CODE_OF_CONDUCT.md) and the [Contributing Guide](https://github.com/appwrite/appwrite/blob/master/CONTRIBUTING.md). ## Getting started @@ -14,7 +14,7 @@ It's really easy to contribute to an open source project, but when using GitHub, > If you are experienced with GitHub or have made a pull request before, you can skip to [Implement new provider](#2-implement-new-provider). -### 1.1 Fork the Appwrite repository +### 1.1 Fork the Appwrite repository Before making any changes, you will need to fork Appwrite's repository to keep branches on the official repo clean. To do that, visit the [Appwrite Github repository](https://github.com/appwrite/appwrite) and click on the fork button. @@ -42,10 +42,10 @@ app/config/providers.php Make sure to fill in all data needed and that your provider array key name: -- is in [`camelCase`](https://en.wikipedia.org/wiki/Camel_case) format +- is in [`camelCase`](https://en.wikipedia.org/wiki/Camel_case) format - has no spaces or special characters -> Please make sure to keep the list of providers in `providers.php` in the alphabetical order A-Z. +> Please make sure to keep the list of providers in `providers.php` in the alphabetical order A-Z. ### 2.2 Add Provider Logo @@ -56,6 +56,7 @@ Add a logo image to your new provider in this path: `public/images/users`. Your Once you have finished setting up all the metadata for the new provider, you need to start coding. Create a new file `XXX.php` where `XXX` is the name of the OAuth provider in [`PascalCase`](https://stackoverflow.com/a/41769355/7659504) in this location + ```bash src/Appwrite/Auth/OAuth2/XXX.php ``` @@ -212,6 +213,7 @@ $provider = $this->getParam('provider', ''); ``` 2. Add the config for creating the JSON in `public/scripts/views/forms/oauth-custom.js` using this template + ```js { "[Provider]":{ diff --git a/docs/tutorials/add-route.md b/docs/tutorials/add-route.md index 6b1bf7e7cf..f66276e973 100644 --- a/docs/tutorials/add-route.md +++ b/docs/tutorials/add-route.md @@ -1,29 +1,37 @@ # Adding Route ๐Ÿ›ก -This document is part of the Appwrite contributors' guide. Before you continue reading this document make sure you have read the [Code of Conduct](https://github.com/appwrite/appwrite/blob/master/CODE_OF_CONDUCT.md) and the [Contributing Guide](https://github.com/appwrite/appwrite/blob/master/CONTRIBUTING.md). +This document is part of the Appwrite contributors' guide. Before you continue reading this document make sure you have read the [Code of Conduct](https://github.com/appwrite/.github/blob/main/CODE_OF_CONDUCT.md) and the [Contributing Guide](https://github.com/appwrite/appwrite/blob/master/CONTRIBUTING.md). ### 1. Alias + Setting an alias allows the route to be also accessible from the alias URL. -The first parameter specifies the alias URL, the second parameter specifies default values for route parameters. +The first parameter specifies the alias URL, the second parameter specifies default values for route parameters. + ```php App::post('/v1/storage/buckets/:bucketId/files') ->alias('/v1/storage/files', ['bucketId' => 'default']) ``` ### 2. Description -Used as an abstract description of the route. + +Used as an abstract description of the route. + ```php App::post('/v1/storage/buckets/:bucketId/files') ->desc('Create File') ``` ### 3. Groups + Groups array is used to group one or more routes with one or more hooks functionality. + ```php App::post('/v1/storage/buckets/:bucketId/files') ->groups(['api']) ``` -In the above example groups() is used to define the current route as part of the routes that shares a common init middleware hook. + +In the above example groups() is used to define the current route as part of the routes that shares a common init middleware hook. + ```php App::init() ->groups(['api']) @@ -32,8 +40,8 @@ App::init() ); ``` - ### 4. The Labels Mechanism + Labels are very strait forward and easy to use and understand, but in the same time are very robust. Labels are passed from the controllers route and used to pick up key-value pairs to be handled in a centralized place along the road. @@ -41,7 +49,8 @@ Labels can be used to pass a pattern in order to be replaced in the other end. Appwrite uses different labels to achieve different things, for example: #### Scope -* scope - Defines the route permissions scope. + +- scope - Defines the route permissions scope. ```php App::post('/v1/storage/buckets/:bucketId/files') @@ -49,10 +58,10 @@ App::post('/v1/storage/buckets/:bucketId/files') ``` #### Audit -* audits.event - Identify the log in human-readable text. -* audits.userId - Signals the extraction of $userId in places that it's not available natively. -* audits.resource - Signals the extraction part of the resource. +- audits.event - Identify the log in human-readable text. +- audits.userId - Signals the extraction of $userId in places that it's not available natively. +- audits.resource - Signals the extraction part of the resource. ```php App::post('/v1/account/create') @@ -62,12 +71,13 @@ App::post('/v1/account/create') ``` #### SDK -* sdk.auth - Array of authentication types is passed in order to impose different authentication methods in different situations. -* sdk.namespace - Refers to the route namespace. -* sdk.method - Refers to the sdk method that needs to called. -* sdk.description - Description of the route,using markdown format. -* sdk.sdk.response.code - Refers to the route http response status code expected. -* sdk.auth.response.model - Refers the route http response expected. + +- sdk.auth - Array of authentication types is passed in order to impose different authentication methods in different situations. +- sdk.namespace - Refers to the route namespace. +- sdk.method - Refers to the sdk method that needs to called. +- sdk.description - Description of the route,using markdown format. +- sdk.sdk.response.code - Refers to the route http response status code expected. +- sdk.auth.response.model - Refers the route http response expected. ```php App::post('/v1/account/jwt') @@ -81,8 +91,9 @@ App::post('/v1/account/jwt') ``` #### Cache -* cache - When set to true, signal the use of file cache. -* cache.resource - Identifies the cached resource. + +- cache - When set to true, signal the use of file cache. +- cache.resource - Identifies the cached resource. ```php App::get('/v1/storage/buckets/:bucketId/files/:fileId/preview') @@ -91,22 +102,24 @@ App::get('/v1/storage/buckets/:bucketId/files/:fileId/preview') ``` #### Abuse -* abuse-key - Specifies routes unique abuse key. -* abuse-limit - Specifies the number of times the route can be requested in a time frame, per route. -* abuse-time - Specifies the time frame (in seconds) relevancy of the all other abuse definitions, per route. + +- abuse-key - Specifies routes unique abuse key. +- abuse-limit - Specifies the number of times the route can be requested in a time frame, per route. +- abuse-time - Specifies the time frame (in seconds) relevancy of the all other abuse definitions, per route. When using the example below, we configure the abuse mechanism to allow this key combination -constructed from the combination of the ip, http method, url, userId to hit the route maximum 60 times in 1 hour (60 seconds * 60 minutes). +constructed from the combination of the ip, http method, url, userId to hit the route maximum 60 times in 1 hour (60 seconds \* 60 minutes). ```php App::post('/v1/storage/buckets/:bucketId/files') ->label('abuse-key', 'ip:{ip},method:{method},url:{url},userId:{userId}') ->label('abuse-limit', 60) - ->label('abuse-time', 3600) + ->label('abuse-time', 3600) ``` #### Events -* event - A pattern that is associated with the route in behalf of realtime messaging. + +- event - A pattern that is associated with the route in behalf of realtime messaging. Placeholders marked as `[]` are parsed and replaced with their real values. ```php @@ -115,8 +128,10 @@ App::post('/v1/storage/buckets/:bucketId/files') ``` #### Usage -* usage.metric - The metric the route generates. -* usage.params - Additional parameters the metrics can have. + +- usage.metric - The metric the route generates. +- usage.params - Additional parameters the metrics can have. + ```php App::post('/v1/storage/buckets/:bucketId/files') ->label('usage.metric', 'files.{scope}.requests.create') @@ -124,23 +139,25 @@ App::post('/v1/storage/buckets/:bucketId/files') ``` ### 5. Param + As the name implies, `param()` is used to define a request parameter. `param()` accepts 6 parameters : -* A key (name) -* A default value -* An instance of a validator class,This can also accept a callback that returns a validator instance. Dependency injection is supported for the callback. -* Description of the parameter -* Is the route optional -* An array of injections + +- A key (name) +- A default value +- An instance of a validator class,This can also accept a callback that returns a validator instance. Dependency injection is supported for the callback. +- Description of the parameter +- Is the route optional +- An array of injections ```php App::get('/v1/account/logs') ->param('queries', [], new Queries(new Limit(), new Offset()), 'Array of query strings generated using the Query class provided by the SDK. [Learn more about queries](https://appwrite.io/docs/databases#querying-documents). Only supported methods are limit and offset', true) ``` - ### 6. inject + inject is used to inject dependencies pre-bounded to the app. ```php @@ -157,6 +174,7 @@ some code... ``` ### 6. Action + Action populates the actual routes code and has to be very clear and understandable. A good route stay simple and doesn't contain complex logic. An action is where we describe our business need in code, and combine different libraries to work together and tell our story. ```php diff --git a/docs/tutorials/add-runtime.md b/docs/tutorials/add-runtime.md index ea8eb4dd82..3f617e909e 100644 --- a/docs/tutorials/add-runtime.md +++ b/docs/tutorials/add-runtime.md @@ -1,19 +1,22 @@ # Creating a new functions runtime ๐Ÿƒ -This document is part of the Appwrite contributors' guide. Before you continue reading this document make sure you have read the [Code of Conduct](https://github.com/appwrite/appwrite/blob/master/CODE_OF_CONDUCT.md) and the [Contributing Guide](https://github.com/appwrite/appwrite/blob/master/CONTRIBUTING.md). +This document is part of the Appwrite contributors' guide. Before you continue reading this document make sure you have read the [Code of Conduct](https://github.com/appwrite/.github/blob/main/CODE_OF_CONDUCT.md) and the [Contributing Guide](https://github.com/appwrite/appwrite/blob/master/CONTRIBUTING.md). ## Getting started + Function Runtimes allow you to execute code written in any language and form the basis of Appwrite's Cloud Functions! Appwrite's goal is to support as many function runtimes as possible. ## 1. Prerequisites + For a function runtime to work, two prerequisites **must** be met due to the way Appwrite's Runtime Execution Model works: - - [ ] The Language in question must be able to run a web server that can serve JSON and text. - - [ ] The Runtime must be able to be packaged into a Docker container - - Note: Both Compiled and Interpreted languages work with Appwrite's execution model but are written in slightly different ways. +- [ ] The Language in question must be able to run a web server that can serve JSON and text. +- [ ] The Runtime must be able to be packaged into a Docker container + +Note: Both Compiled and Interpreted languages work with Appwrite's execution model but are written in slightly different ways. It's really easy to contribute to an open-source project, but when using GitHub, there are a few steps we need to follow. This section will take you step-by-step through the process of preparing your local version of Appwrite, where you can make any changes without affecting Appwrite right away. + > If you are experienced with GitHub or have made a pull request before, you can skip to [Implement new runtime](https://github.com/appwrite/appwrite/blob/master/docs/tutorials/add-runtime.md#2-implement-new-runtime). ### 1.1 Fork the Appwrite repository @@ -23,6 +26,7 @@ Before making any changes, you will need to fork Appwrite's repository to keep b [![Fork button](https://github.com/appwrite/appwrite/raw/master/docs/tutorials/images/fork.png)](https://github.com/appwrite/appwrite/blob/master/docs/tutorials/images/fork.png) This will redirect you from `github.com/appwrite/runtimes` to `github.com/YOUR_USERNAME/runtimes`, meaning all changes you do are only done inside your repository. Once you are there, click the highlighted `Code` button, copy the URL and clone the repository to your computer using the `git clone` command: + ```bash $ git clone COPIED_URL ``` @@ -34,15 +38,18 @@ Finally, you will need to create a `feat-XXX-YYY-runtime` branch based on the `r ## 2. Implement new runtime ### 2.1 Preparing the files for your new runtime + The first step to writing a new runtime is to create a folder within `/runtimes` with the name of the runtime and the version separated by a dash. For instance, if I was to write a Rust Runtime with version 1.55 the folder name would be: `rust-1.55` Within that folder you will need to create a few basic files that all Appwrite runtimes require: + ``` Dockerfile - Dockerfile that explains how the container will be built. README.md - A readme file explaining the runtime and any special notes for the runtime. A good example of this is the PHP 8.0 runtime. ``` ### 2.2 Differences between compiled and interpreted runtimes + Runtimes within Appwrite are created differently depending on whether they are compiled or interpreted. This is due to the fundamental differences between the two ways of running the code. Interpreted languages have both a `build.sh` file and a `launch.sh` file. @@ -52,38 +59,45 @@ The build script is always executed during the build stage of tag deployment. The `launch.sh` file for an interpreted runtime should extract the `/tmp/code.tar.gz` file that contains both the user's code and the dependencies. This tarball was created by Appwrite from the `/usr/code` folder and should install the dependencies that were pre-installed by the build stage and move them into the relevant locations for that runtime. It will then run the server ready for execution. --- + Compiled Languages only have a `build.sh` file. The `build.sh` script for a compiled runtime is used to move the user's source code and rename it into source files for the runtime (The `ENTRYPOINT_NAME` environment variable can help with this) it will also build the code and move it into the `/usr/code` folder. Compiled runtime executables **must** be called `runtime` for the ubuntu or alpine images to detect and run them. #### Note: + `/tmp/code.tar.gz` is always created from the `/usr/code` folder in the build stage. If you need any files for either compiled or interpreted runtimes you should place them there and extract them from the `/tmp/code.tar.gz` during the `launch.sh` script to get the files you need. ### 2.3 Writing the runtime + Internally the runtime can be anything you like as long as it follows the standards set by the other runtimes. The best way to go about writing a runtime is like so: Initialize a web server that runs on port 3000 and uses any IP Address (0.0.0.0) and on each `POST` request do the following: + 1. Check that the `x-internal-challenge` header matches the `INTERNAL_RUNTIME_KEY` environment variable. If not return an error with a `401` status code and an `unauthorized` error message. 2. Decode the executor's JSON POST request. This normally looks like so: + ```json { - "path": "/usr/code", - "file": "index.js", - "env": { - "hello":"world!" - }, - "payload":"An Example Payload", - "timeout": 10 + "path": "/usr/code", + "file": "index.js", + "env": { + "hello": "world!" + }, + "payload": "An Example Payload", + "timeout": 10 } ``` + For a compiled language you can disregard the `path` and `file` attribute if you like, `timeout` is also an optional parameter to deal with, if you can handle it please do. Otherwise, it doesn't matter since the connection will simply be dropped by the executor. You must create two classes for users to use within their scripts. A `Request` Class and a `Response` class -The `Request` class must store `env`, `payload` and `headers` and pass them to the user's function. +The `Request` class must store `env`, `payload` and `headers` and pass them to the user's function. The Request always goes before the response in the user's function parameters. -The `Response` class must have two functions. +The `Response` class must have two functions. + - A `send(string)` function which will return text to the request - and a `json(object)` function which will return JSON to the request setting the appropriate headers @@ -93,32 +107,39 @@ Please make sure to add appropriate checks to make sure the imported file is a f 5. Finally execute the function and handle whatever response the user's code returns. Try to wrap the function into a `try catch` statement to handle any errors the user's function encounters and return them cleanly to the executor with the error schema. ### 2.4 The Error Schema + All errors that occur during the execution of a user's function **MUST** be returned using this JSON Object otherwise Appwrite will be unable to parse them for the user. + ```json { - "code": 500, // (Int) Use 404 if function not found or use 401 if the x-internal-challenge check failed. - "message": "Error: Tried to divide by 0 \n /usr/code/index.js:80:7", // (String) Try to return a stacktrace and detailed error message if possible. This is shown to the user. + "code": 500, // (Int) Use 404 if function not found or use 401 if the x-internal-challenge check failed. + "message": "Error: Tried to divide by 0 \n /usr/code/index.js:80:7" // (String) Try to return a stacktrace and detailed error message if possible. This is shown to the user. } ``` ### 2.5 Writing your Dockerfile + The Dockerfile is very important as it's the environment you are creating to run build the runtime and also run the code if you are writing an Interpreted Runtime (Compiled runtimes will use an alpine or ubuntu image) The first thing you need to do is find a docker image to base your runtime off, You can find these at [Docker Hub](https://hub.docker.com). If possible try to use verified official builds of the language you are creating a runtime for. Next in your Dockerfile at the start add the docker image you want to base it off at the top like so: + ```bash FROM Dart:2.12 # Dart is used as an example. ``` + This will download and require the image when you build your runtime and allow you to use the toolset of the language you are building a runtime for. Create a user and group for the runtime, this user will be used to both build and run the code: + ```bash RUN groupadd -g 2000 appwrite \ && useradd -m -u 2001 -g appwrite appwrite ``` then create the folders you will use in your build step: + ```bash RUN mkdir -p /usr/local/src/ RUN mkdir -p /usr/code @@ -127,21 +148,25 @@ RUN mkdir -p /usr/builtCode ``` Next copy your source code and set the working directory for the image like so: + ``` WORKDIR /usr/local/src COPY . /usr/local/src ``` Next, you want to make sure you are adding execute permissions to any scripts you may run, the main ones are `build.sh` and `launch.sh`. You can run commands in Dockerfile's using the `RUN` prefix like so: + ``` RUN chmod +x ./build.sh RUN chmod +x ./launch.sh ``` + Note: Do not chmod a `launch.sh` file if you don't have one. If needed use the `RUN` commands to install any dependencies you require for the build stage. Next set the permissions for the user you created so your build and run step will have access to them: + ``` RUN ["chown", "-R", "appwrite:appwrite", "/usr/local/src"] RUN ["chown", "-R", "appwrite:appwrite", "/usr/code"] @@ -150,57 +175,72 @@ RUN ["chown", "-R", "appwrite:appwrite", "/usr/builtCode"] ``` Finally, you'll add a `CMD` command. For an interpreted language this should be: + ``` CMD ["/usr/local/src/launch.sh"] ``` + Since this will use your launch script when the runtime starts. For a compiled language this must be: + ``` CMD ["tail", "-f", "/dev/null"] ``` + so the build steps can be run. ## 3. Building your Docker image and adding it to the list + With your runtime successfully created you can now move on to building your docker image and adding it to the script files used for generating all of the image files. Open up the `/runtimes/buildLocalOnly.sh` script first and add your runtime to it. The following is an example with dart version 2.12 + ``` echo 'Dart 2.12...' docker build -t dart-runtime:2.12 ./runtimes/dart-2.12 ``` + Next, open up the `/runtimes/build.sh` script and also add your runtime to it. This one is slightly different as this is the one that will be used for cross-platform compiles and deploying it to Docker hub. The following is an example also with dart version 2.12: + ``` echo 'Dart 2.12...' docker buildx build --platform linux/amd64,linux/arm64 -t dart-runtime:2.12 ./runtimes/dart-2.12/ --push ``` ## 4. Adding the runtime to the runtimes list + In `src/Runtimes/Runtimes` create a new entry in the `__construct()` method in the Runtimes class like so: + ``` $dart = new Runtime('dart', 'Dart'); $dart->addVersion('2.12', 'dart-runtime:2.12', 'appwrite-ubuntu:20.04', [System::X86, System::ARM]); $this->runtimes['dart'] = $dart; ``` + This is an example of what you would do for a compiled language such as dart. The first line is creating a new language entry, The first parameter is the internal name and the second one is the external one which is what the user will see in Appwrite. The second line adds a new version to the language entry, I'll break down the parameters: + ``` 1: Version - The version of the runtime you are creating. 2: Build Image - The image used to build the code -3: Run Image - The image used to run the code. +3: Run Image - The image used to run the code. For interpreted languages, this is normally the same as the Build Image, but for compiled languages, this can be either "appwrite-alpine:3.13.6" or "appwrite-ubuntu:20.04" We recommend using Alpine when possible and using Ubuntu if the runtime doesn't work on Alpine. 4: Platforms Supported - These are the architectures this runtime is available to. ``` + The third line simply adds the new runtime to the main list. ## 5. Adding tests ### 5.1 Writing your test execution script + Adding tests for your runtime is simple, go into the `/tests/resources` folder and create a folder for the language you are creating then within the folder create a source code file for the language you are writing a runtime for as if you were creating a user function for your runtime. Within this user function you are writing all you need to do is return some JSON with the following schema: + ```json { "normal": "Hello World!", @@ -208,29 +248,37 @@ Adding tests for your runtime is simple, go into the `/tests/resources` folder a "payload": request.payload, // Payload from the request } ``` + ### 5.2 Creating the test packaging script for your runtime -With your test execution written you can move on to writing the script used to package your test execution script into a tarball for later use by the test system. Move into `/test/resources` again and notice how we have shell scripts for all runtimes we have made tests for. + +With your test execution written you can move on to writing the script used to package your test execution script into a tarball for later use by the test system. Move into `/test/resources` again and notice how we have shell scripts for all runtimes we have made tests for. Next create a shell script yourself with your language name. As an example, the shell script name for dart would be `package-dart.sh` Within this newly created script copy-paste this script and replace all the `LANGUAGE_NAME` parts with your language's name + ``` echo 'LANGUAGE_NAME Packaging...' rm $(pwd)/tests/resources/LANGUAGE_NAME.tar.gz tar -zcvf $(pwd)/tests/resources/LANGUAGE_NAME.tar.gz -C $(pwd)/tests/resources/LANGUAGE_NAME . ``` + Then save this file. Then `cd` into the root of the `runtimes` project in a terminal. Run the following command replacing the `LANGUAGE_NAME` with your language's name: + ``` chmod +x ./tests/resources/package-LANGUAGE_NAME.sh && ./tests/resources/package-LANGUAGE_NAME.sh ``` + This command adds execution permissions to your script and executes it. NOTE: If you ever want to repackage your script you can simply run: `./tests/resources/package-LANGUAGE_NAME.sh` in the root of the `runtimes` project since you don't have to change permissions more than once. ### 5.3 Adding your runtime to the main testing script + Now you have created your test execution script and have packaged it up for your runtime to execute you can now add it to the main testing script. Open up the `./tests/Runtimes/RuntimesTest.php` file and find the part where we are defining `$this->tests`. Once you have found this, Add your own entry into this array like so: + ```php 'LANGUAGE_NAME-VERSION' => [ 'code' => $functionsDir . ' /LANGUAGE_NAME.tar.gz', @@ -240,16 +288,19 @@ Once you have found this, Add your own entry into this array like so: 'tarname' => 'LANGUAGE_NAME-VERSION.tar.gz', // Note: If your version has a point in it replace it with a dash instead for this value. ], ``` + Make sure to replace all instances of `LANGUAGE_NAME` with your language's name and `VERSION` with your runtime's version. Once you have done this and saved it, it is finally time to move onto one of the final steps. ### 5.4 Running the tests. + Running the tests is easy, simply run `docker compose up` in the root of the `runtimes` folder. This will launch a Docker container with the test script and start running through all the runtimes making sure to test them thoroughly. If all tests pass then congratulations! You can now go ahead and file a PR against the `runtimes` repo making sure to target the `refactor` branch, make sure you're ready to respond to any feedback which can arise during our code review. ## 6. Raise a pull request + First of all, commit the changes with the message `Added XXX Runtime` and push it. This will publish a new branch to your forked version of Appwrite. If you visit it at `github.com/YOUR_USERNAME/runtimes`, you will see a new alert saying you are ready to submit a pull request. Follow the steps GitHub provides, and at the end, you will have your pull request submitted. ## ![face_with_head_bandage](https://github.githubassets.com/images/icons/emoji/unicode/1f915.png) Stuck ? diff --git a/docs/tutorials/add-storage-adapter.md b/docs/tutorials/add-storage-adapter.md index 26a7167ddd..97530e95bb 100644 --- a/docs/tutorials/add-storage-adapter.md +++ b/docs/tutorials/add-storage-adapter.md @@ -1,6 +1,6 @@ # Adding a New Storage Adapter -This document is part of the Appwrite contributors' guide. Before you continue reading this document make sure you have read the [Code of Conduct](https://github.com/appwrite/appwrite/blob/master/CODE_OF_CONDUCT.md) and the [Contributing Guide](https://github.com/appwrite/appwrite/blob/master/CONTRIBUTING.md). +This document is part of the Appwrite contributors' guide. Before you continue reading this document make sure you have read the [Code of Conduct](https://github.com/appwrite/.github/blob/main/CODE_OF_CONDUCT.md) and the [Contributing Guide](https://github.com/appwrite/appwrite/blob/master/CONTRIBUTING.md). ## Getting Started @@ -11,9 +11,11 @@ Storage providers help us use various storage services to store our Appwrite dat As the storage library is separated into [utopia-php/storage](https://github.com/utopia-php/storage), adding new storage adapter will consist of two phases. First adding and implementing the new adapter in the [utopia-php/storage](https://github.com/utopia-php/storage) and then adding support to the new storage adapter in Appwrite. ### Phase 1 + In phase 1, we will introduce and implement the new device adapter in [utopia-php/storage](https://github.com/utopia-php/storage) library. ### Add new adapter + Add a new storage adapter inside `src/Storage/Device/` folder. Use one of the existing ones as a reference. The new adapter class should extend `Device` class and implement all the required methods. Note that the class name should start with a capital letter as PHP FIG standards suggest. @@ -21,31 +23,39 @@ Note that the class name should start with a capital letter as PHP FIG standards Always use properly named environment variables if any credentials are required. ### Introduce new device constant + Introduce newly added device constant in `src/Storage/Storage.php` alongside existing device constants. The device constant should start with `const DEVICE_` as the existing ones. ### Introduce new device tests + Add tests for the newly added device adapter inside `tests/Storage/Device`. Use the existing adapter tests as a reference. The test file and class should be properly named `Test.php` and class should be `Test` ### Run and verify tests + Run tests using `vendor/bin/phpunit --configuration phpunit.xml` and verify that everything is working correctly. If everything goes well, create a new pull request in [utopia-php/storage](https://github.com/utopia-php/storage) library. ### Phase 2 + In this phase we will add support to the new storage adapter in Appwrite. -* Note for this to happen, your PR in the first phase should have been merged and new version of [utopia-php/storage](https://github.com/utopia-php/storage) library released. +- Note for this to happen, your PR in the first phase should have been merged and new version of [utopia-php/storage](https://github.com/utopia-php/storage) library released. ### Upgrade the utopia-php/storage dependency + Upgrade the utopia-php/storage dependency in `composer.json` file. ### Introduce new environment variables + If required for the new adapter, may be for credentials, introduce new environment variables. The storage environment variables are prefixed as `_APP_STORAGE_DEVICE`. Please read [Adding Environment Variables]() guidelines in order to properly introduce new environment variables. ### Implement the device case + In `app/controllers/shared/api.php` inside init function, there is a `switch/case` statements for each supported storage device. Implement the instantiation of your device type for your device case. The device cases are the devices constants listed in the `uptopa-php/storage/Storage` class. ### Test and verify everything works + To test you can switch to your newly added device using `_APP_STORAGE_DEVICE` environment variable. Then run `docker compose build && docker compose up -d` in order to build the containers with updated changes. Once the containers are running, login to Appwrite console and create a project. Then in storage section, try to upload, preview, delete files. If everything goes well, initiate a pull request to appwrite repository. diff --git a/docs/tutorials/add-translations.md b/docs/tutorials/add-translations.md index 26fe65c948..fbceebbe0a 100644 --- a/docs/tutorials/add-translations.md +++ b/docs/tutorials/add-translations.md @@ -1,16 +1,16 @@ # Help translate Appwrite to your language โœ๏ธ -This document is part of the Appwrite contributors' guide. Before you continue reading this document make sure you have read the [Code of Conduct](https://github.com/appwrite/appwrite/blob/master/CODE_OF_CONDUCT.md) and the [Contributing Guide](https://github.com/appwrite/appwrite/blob/master/CONTRIBUTING.md). +This document is part of the Appwrite contributors' guide. Before you continue reading this document make sure you have read the [Code of Conduct](https://github.com/appwrite/.github/blob/main/CODE_OF_CONDUCT.md) and the [Contributing Guide](https://github.com/appwrite/appwrite/blob/master/CONTRIBUTING.md). ## Getting started -Appwrite's Locale API, Email Templates ( and soon our Dashboard ) has support for returning responses in your own locale based on the value of the `X-Appwrite-Locale` header. Behind the scenes, we use the value of this header to find the correct translation file for the locale. This guide will walk you through the process of adding a new Locale to Appwrite. +Appwrite's Locale API, Email Templates ( and soon our Dashboard ) has support for returning responses in your own locale based on the value of the `X-Appwrite-Locale` header. Behind the scenes, we use the value of this header to find the correct translation file for the locale. This guide will walk you through the process of adding a new Locale to Appwrite. You can help in three distinct ways: -* Adding support for new locales -* Helping us with existing incomplete translations -* Reviewing existing translations for correctness +- Adding support for new locales +- Helping us with existing incomplete translations +- Reviewing existing translations for correctness ## 1. Prerequisites @@ -18,7 +18,7 @@ It's really easy to contribute to an open-sourced project, but when using GitHub > If you are experienced with GitHub or have made a pull request before, you can skip to [Generate the translations](#2-generate-the-translations). -### 1.1 Fork the Appwrite repository +### 1.1 Fork the Appwrite repository Before making any changes, you will need to fork Appwrite's repository to keep branches on the official repo clean. To do that, visit the [Appwrite Github repository](https://github.com/appwrite/appwrite) and click on the fork button. @@ -34,56 +34,54 @@ $ git clone COPIED_URL Finally, you will need to create a `feat-XXX-YYY-translation` branch based on the `locale` branch and switch to it. The `XXX` should represent issue ID and `YYY` the language name. - ## 2. Generate the translations You can choose to contribute either directly on [**GitHub**](#21-manually-using-github) or using [**POEditor**](#22-visually-using-po-editor) if you prefer a GUI. ### 2.1 Manually using GitHub - -> Proceed to [Visually using PO Editor](#22-visually-using-po-editor) if you want to use graphical interface instead. +> Proceed to [Visually using PO Editor](#22-visually-using-po-editor) if you want to use graphical interface instead. We maintain a [`locale branch`](https://github.com/appwrite/appwrite/tree/locale/) under the [appwrite/appwrite repo](https://github.com/appwrite/appwrite/) exclusively for translations related PRs. Here are a few files that you need to refer to help with your contribution. 1. **terms.json** - [terms.json](https://github.com/appwrite/appwrite/blob/locale/app/config/locale/terms.json) contains all the terms that are used in Appwrite that require translation. Each term is a JSON object as shown below. + [terms.json](https://github.com/appwrite/appwrite/blob/locale/app/config/locale/terms.json) contains all the terms that are used in Appwrite that require translation. Each term is a JSON object as shown below. - ```json - [ - { - "term": "settings.inspire", - "comment": "This string is used as an easter egg in the appwrite.io source code.", - "reference": "" - } - ] - ``` + ```json + [ + { + "term": "settings.inspire", + "comment": "This string is used as an easter egg in the appwrite.io source code.", + "reference": "" + } + ] + ``` 2. **en.json** - [en.json](https://github.com/appwrite/appwrite/blob/locale/app/config/locale/translations/en.json) contains the English translation for all the terms that are present in **terms.json**. You can use this file as a reference when making a contribution for your language. + [en.json](https://github.com/appwrite/appwrite/blob/locale/app/config/locale/translations/en.json) contains the English translation for all the terms that are present in **terms.json**. You can use this file as a reference when making a contribution for your language. - ```json - { - "settings.inspire": "\"The art of being wise is the art of knowing what to overlook.\"", - "settings.locale": "en", - "settings.direction": "ltr", - "emails.sender": "%s Team", - .... - .... - } - ``` + ```json + { + "settings.inspire": "\"The art of being wise is the art of knowing what to overlook.\"", + "settings.locale": "en", + "settings.direction": "ltr", + "emails.sender": "%s Team", + .... + .... + } + ``` 3. **languages.php** - [languages.php](https://github.com/appwrite/appwrite/blob/locale/app/config/locale/languages.php) contains all the languages listed in **[ISO 639-1](https://en.wikipedia.org/wiki/List_of_ISO_639-1_codes)**. You can use this file to find your language code when making a contribution for your language. + [languages.php](https://github.com/appwrite/appwrite/blob/locale/app/config/locale/languages.php) contains all the languages listed in **[ISO 639-1](https://en.wikipedia.org/wiki/List_of_ISO_639-1_codes)**. You can use this file to find your language code when making a contribution for your language. Great, let's start. First, find the code of the language you want to add. For example, if you want to add support for **Spanish**, you can find the code for Spanish in [languages.php](https://github.com/appwrite/appwrite/blob/locale/app/config/locale/languages.php#L202). -Once you have found the ISO language code for **Spanish** (es), create a new file `/app/config/locale/translations/es.json` just like all [the other languages](https://github.com/appwrite/appwrite/tree/locale/app/config/locale/translations). +Once you have found the ISO language code for **Spanish** (es), create a new file `/app/config/locale/translations/es.json` just like all [the other languages](https://github.com/appwrite/appwrite/tree/locale/app/config/locale/translations). -Next, choose a reference language. If English is your reference language, copy the contents of [`en.json`](https://github.com/appwrite/appwrite/blob/locale/app/config/locale/translations/en.json) into `/app/config/locale/translations/es.json` and translate all the corresponding strings like so +Next, choose a reference language. If English is your reference language, copy the contents of [`en.json`](https://github.com/appwrite/appwrite/blob/locale/app/config/locale/translations/en.json) into `/app/config/locale/translations/es.json` and translate all the corresponding strings like so ```json { @@ -99,7 +97,7 @@ Next, choose a reference language. If English is your reference language, copy t > Proceed to [Add the translations to the project](#3-add-the-translations-to-the-project) if you already followed the GitHub approach. -We use [PO Editor](https://poeditor.com/) to manage all our translations in a convenient way. The first step is to join the Appwrite Project on PO Editor using [our invite link](https://poeditor.com/join/project?hash=BNrWbRXyk6). +We use [PO Editor](https://poeditor.com/) to manage all our translations in a convenient way. The first step is to join the Appwrite Project on PO Editor using [our invite link](https://poeditor.com/join/project?hash=BNrWbRXyk6). On the home page, you can see all the languages that we currently support and the progress in each one. You can choose to help us complete the existing translations or add new ones. @@ -115,7 +113,7 @@ Your request might be pending, so you can ping us on Discord and we'll make the ![Get Started](images/guide.png) -You're now ready to start contributing. On the left, you'll find the string to be translated in the default reference language ( which is English ). You can also change the default language to something that you're more familiar with using the toggle. +You're now ready to start contributing. On the left, you'll find the string to be translated in the default reference language ( which is English ). You can also change the default language to something that you're more familiar with using the toggle. ![Reference Language](images/reference-language.png) @@ -127,10 +125,10 @@ Once you're happy with your translations, you can export them. Head over to the After exporting a JSON file, we need to rename it to follow the **[ISO 639-1](https://en.wikipedia.org/wiki/List_of_ISO_639-1_codes)** standards. You can use [languages.php](https://github.com/appwrite/appwrite/blob/locale/app/config/locale/languages.php) file to find your language code when making a contribution for your language. For example, Spanish translation should have file called `es.json`. - ## 3. Add the translations to the project Add your language code to [codes.php](https://github.com/appwrite/appwrite/blob/locale/app/config/locale/codes.php#L14) in the following format. + ```php ... 'es', // Spanish @@ -139,7 +137,7 @@ Add your language code to [codes.php](https://github.com/appwrite/appwrite/blob/ Finally, load your translation file in `init.php` by following a pattern similar to the [existing languages](https://github.com/appwrite/appwrite/blob/locale/app/init.php#L270). -> Please make sure to keep both `codes.php` and `init.php` in the alphabetical order A-Z. +> Please make sure to keep both `codes.php` and `init.php` in the alphabetical order A-Z. ## 4. Test the translations @@ -155,7 +153,6 @@ If this is your first time running Appwrite, it may take up to few minutes to do If you are lost in the Appwrite dashboard, check out our [Article about Appwrite's dashboard](https://dev.to/appwrite/30daysofappwrite-appwrite-dashboard-15cc). - Now, let's send the request. We will be editing headers of the request, so you will need a tool to do that, such as Postman or Insomnia. First, let's see English translations. Let's set request type to `GET`, URL to `https://localhost/v1/locale/countries/eu` and add `X-Appwrite-Project` header. @@ -179,4 +176,5 @@ If you can see countries names translated, everything works, and you are ready f First of all, commit the changes with the message `Added YYY translations` where `YYY` is the translated language and push it. This will publish a new branch to your forked version of Appwrite. If you visit it at `github.com/YOUR_USERNAME/appwrite`, you will see a new alert saying you are ready to submit a pull request. Follow the steps GitHub provides, and at the end, you will have your pull request submitted. ## ๐Ÿค• Stuck ? + If you need any help with the contribution, feel free to head over to [our Discord channel](https://appwrite.io/discord) and we'll be happy to help you out. From 36cc6d8621ebe093a9d6bfc44eefb94ed8269b3a Mon Sep 17 00:00:00 2001 From: Torsten Dittmann Date: Thu, 17 Nov 2022 14:38:49 +0100 Subject: [PATCH 5/9] chore: prepare 1.1.1 release --- README-CN.md | 6 +++--- README.md | 6 +++--- app/init.php | 2 +- src/Appwrite/Migration/Migration.php | 1 + 4 files changed, 8 insertions(+), 7 deletions(-) diff --git a/README-CN.md b/README-CN.md index 3dc0f6ff1d..4f8156f2ce 100644 --- a/README-CN.md +++ b/README-CN.md @@ -64,7 +64,7 @@ docker run -it --rm \ --volume /var/run/docker.sock:/var/run/docker.sock \ --volume "$(pwd)"/appwrite:/usr/src/code/appwrite:rw \ --entrypoint="install" \ - appwrite/appwrite:1.1.0 + appwrite/appwrite:1.1.1 ``` ### Windows @@ -76,7 +76,7 @@ docker run -it --rm ^ --volume //var/run/docker.sock:/var/run/docker.sock ^ --volume "%cd%"/appwrite:/usr/src/code/appwrite:rw ^ --entrypoint="install" ^ - appwrite/appwrite:1.1.0 + appwrite/appwrite:1.1.1 ``` #### PowerShell @@ -86,7 +86,7 @@ docker run -it --rm , --volume /var/run/docker.sock:/var/run/docker.sock , --volume ${pwd}/appwrite:/usr/src/code/appwrite:rw , --entrypoint="install" , - appwrite/appwrite:1.1.0 + appwrite/appwrite:1.1.1 ``` ่ฟ่กŒๅŽ๏ผŒๅฏไปฅๅœจๆต่งˆๅ™จไธŠ่ฎฟ้—ฎ http://localhost ๆ‰พๅˆฐ Appwrite ๆŽงๅˆถๅฐใ€‚ๅœจ้ž Linux ็š„ๆœฌๆœบไธปๆœบไธŠๅฎŒๆˆๅฎ‰่ฃ…ๅŽ๏ผŒๆœๅŠกๅ™จๅฏ่ƒฝ้œ€่ฆๅ‡ ๅˆ†้’Ÿๆ‰่ƒฝๅฏๅŠจใ€‚ diff --git a/README.md b/README.md index 28b1ae6d7e..6942597115 100644 --- a/README.md +++ b/README.md @@ -75,7 +75,7 @@ docker run -it --rm \ --volume /var/run/docker.sock:/var/run/docker.sock \ --volume "$(pwd)"/appwrite:/usr/src/code/appwrite:rw \ --entrypoint="install" \ - appwrite/appwrite:1.1.0 + appwrite/appwrite:1.1.1 ``` ### Windows @@ -87,7 +87,7 @@ docker run -it --rm ^ --volume //var/run/docker.sock:/var/run/docker.sock ^ --volume "%cd%"/appwrite:/usr/src/code/appwrite:rw ^ --entrypoint="install" ^ - appwrite/appwrite:1.1.0 + appwrite/appwrite:1.1.1 ``` #### PowerShell @@ -97,7 +97,7 @@ docker run -it --rm ` --volume /var/run/docker.sock:/var/run/docker.sock ` --volume ${pwd}/appwrite:/usr/src/code/appwrite:rw ` --entrypoint="install" ` - appwrite/appwrite:1.1.0 + appwrite/appwrite:1.1.1 ``` Once the Docker installation completes, go to http://localhost to access the Appwrite console from your browser. Please note that on non-Linux native hosts, the server might take a few minutes to start after installation completes. diff --git a/app/init.php b/app/init.php index c9a6097ab4..3d24ef81d4 100644 --- a/app/init.php +++ b/app/init.php @@ -95,7 +95,7 @@ const APP_LIMIT_WRITE_RATE_PERIOD_DEFAULT = 60; // Default maximum write rate pe const APP_KEY_ACCCESS = 24 * 60 * 60; // 24 hours const APP_CACHE_UPDATE = 24 * 60 * 60; // 24 hours const APP_CACHE_BUSTER = 501; -const APP_VERSION_STABLE = '1.1.0'; +const APP_VERSION_STABLE = '1.1.1'; const APP_DATABASE_ATTRIBUTE_EMAIL = 'email'; const APP_DATABASE_ATTRIBUTE_ENUM = 'enum'; const APP_DATABASE_ATTRIBUTE_IP = 'ip'; diff --git a/src/Appwrite/Migration/Migration.php b/src/Appwrite/Migration/Migration.php index 9c6b03391c..6c293723e1 100644 --- a/src/Appwrite/Migration/Migration.php +++ b/src/Appwrite/Migration/Migration.php @@ -46,6 +46,7 @@ abstract class Migration '1.0.1' => 'V15', '1.0.3' => 'V15', '1.1.0' => 'V16', + '1.1.1' => 'V16', ]; /** From 727c3839d608ce564fdaaa6132b97ed66035104d Mon Sep 17 00:00:00 2001 From: Torsten Dittmann Date: Thu, 17 Nov 2022 14:52:44 +0100 Subject: [PATCH 6/9] feat: upgrade console to 2.0.1 --- .gitmodules | 2 +- app/console | 2 +- 2 files changed, 2 insertions(+), 2 deletions(-) diff --git a/.gitmodules b/.gitmodules index dc04bee3cb..e9f13bb1ac 100644 --- a/.gitmodules +++ b/.gitmodules @@ -1,4 +1,4 @@ [submodule "app/console"] path = app/console url = https://github.com/appwrite/console - branch = 2.0.0 + branch = 2.0.1 diff --git a/app/console b/app/console index de73c020a7..f89584bdd4 160000 --- a/app/console +++ b/app/console @@ -1 +1 @@ -Subproject commit de73c020a7798e580c48197816124ca4783e115b +Subproject commit f89584bdd4ba3de07fb54cecbc275b131e23a4fb From d1eae375773c830e5d90bf47381faa687e24bdca Mon Sep 17 00:00:00 2001 From: Torsten Dittmann Date: Thu, 17 Nov 2022 14:57:27 +0100 Subject: [PATCH 7/9] fix: make migration for oauth providers non-destructive --- src/Appwrite/Migration/Version/V16.php | 4 ++++ 1 file changed, 4 insertions(+) diff --git a/src/Appwrite/Migration/Version/V16.php b/src/Appwrite/Migration/Version/V16.php index 070b8e7d92..e86561e42a 100644 --- a/src/Appwrite/Migration/Version/V16.php +++ b/src/Appwrite/Migration/Version/V16.php @@ -130,6 +130,10 @@ class V16 extends Migration } if (($authProviders[$provider . 'Appid'] ?? false) && ($authProviders[$provider . 'Secret'] ?? false)) { + if (array_key_exists($provider . 'Enabled', $authProviders)) { + continue; + } + $authProviders[$provider . 'Enabled'] = true; } } From bba9284c3ebaad1b78addb33f68cbb2ea83c4cb3 Mon Sep 17 00:00:00 2001 From: Torsten Dittmann Date: Thu, 17 Nov 2022 14:58:16 +0100 Subject: [PATCH 8/9] chore: add comments to v16 migration --- src/Appwrite/Migration/Version/V16.php | 4 +++- 1 file changed, 3 insertions(+), 1 deletion(-) diff --git a/src/Appwrite/Migration/Version/V16.php b/src/Appwrite/Migration/Version/V16.php index e86561e42a..80f43d7d43 100644 --- a/src/Appwrite/Migration/Version/V16.php +++ b/src/Appwrite/Migration/Version/V16.php @@ -121,7 +121,9 @@ class V16 extends Migration 'duration' => Auth::TOKEN_EXPIRATION_LOGIN_LONG ])); - + /** + * Enable OAuth providers with data + */ $authProviders = $document->getAttribute('authProviders', []); foreach (Config::getParam('providers') as $provider => $value) { From dd34dfce22a77c7723aa546202ceb3eb2f6330c1 Mon Sep 17 00:00:00 2001 From: Torsten Dittmann Date: Thu, 17 Nov 2022 15:33:46 +0100 Subject: [PATCH 9/9] fix: migration for oauthproviders --- src/Appwrite/Migration/Version/V16.php | 2 ++ 1 file changed, 2 insertions(+) diff --git a/src/Appwrite/Migration/Version/V16.php b/src/Appwrite/Migration/Version/V16.php index 80f43d7d43..1d56b246d6 100644 --- a/src/Appwrite/Migration/Version/V16.php +++ b/src/Appwrite/Migration/Version/V16.php @@ -140,6 +140,8 @@ class V16 extends Migration } } + $document->setAttribute('authProviders', $authProviders); + break; }