Improve README and Contributing Guide

PineappleIOnic · PineappleIOnic · commit dc6f8178965f · 2022-07-19T15:43:23.000+01:00
diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md
@@ -0,0 +1,92 @@
+# Contributing
+
+We would ❤️ for you to contribute to Appwrite and help make it better! As a contributor, here are the guidelines we would like you to follow:
+
+## Code of Conduct
+
+Help us keep Appwrite open and inclusive. Please read and follow our [Code of Conduct](/CODE_OF_CONDUCT.md).
+
+## Submit a Pull Request 🚀
+
+
+Branch naming convention is as following
+
+`TYPE-ISSUE_ID-DESCRIPTION`
+
+example:
+
+```
+doc-548-submit-a-pull-request-section-to-contribution-guide
+```
+
+When `TYPE` can be:
+
+- **feat** - is a new feature
+- **doc** - documentation only changes
+- **cicd** - changes related to CI/CD system
+- **fix** - a bug fix
+- **refactor** - code change that neither fixes a bug nor adds a feature
+
+**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:
+
+1. `git pull`, before creating a new branch, pull the changes from upstream. Your master needs to be up to date.
+
+```
+$ git pull
+```
+
+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]
+```
+
+3. Work - commit - repeat ( be sure to be in your branch )
+
+4. Before you push your changes, make sure your code follows the `Rustfmt` coding standards , which is the standard Appwrite follows currently. You can easily do this by running the formatter.
+
+```bash
+cargo fmt
+```
+
+If the `cargo fmt` command does not work then run the following to install rustfmt:
+
+```bash
+rustup component add rustfmt
+```
+
+This will give you a list of errors for you to rectify
+
+1. Push changes to GitHub
+
+```
+$ 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.
+7. Start a Pull Request
+   Now submit the pull request and click on `Create pull request`.
+8. Get a code review approval/reject
+9. After approval, merge your PR
+10. GitHub will automatically delete the branch after the merge is done. (they can still be restored).
+
+
+## Running Tests
+Tests are run with Docker in order to test both alpine builds and GNU linux builds, Docker Compose is also required.
+
+Bring up the testing containers using:
+```bash
+docker compose up -d --force-recreate --build
+```
+
+Then run the tests using
+```bash
+docker compose exec -T tests_gnu sh -c "cd /src/ && /src/vendor/bin/phpunit"
+
+docker compose exec -T tests_alpine sh -c "cd /src/ && /src/vendor/bin/phpunit"
+```
+
+The first command tests GNU based machines and the second one tests alpine, both must pass before the PR is merged.
diff --git a/README.md b/README.md
@@ -1,28 +1,77 @@
-#  PHP Scrypt
+# PHP Scrypt
 
-A simple PHP Extension written in Rust to create scrypt password hashes.
+[![Discord](https://img.shields.io/discord/564160730845151244?label=discord&style=flat-square)](https://appwrite.io/discord)
+[![Twitter Account](https://img.shields.io/twitter/follow/appwrite?color=00acee&label=twitter&style=flat-square)](https://twitter.com/appwrite)
+[![Follow Appwrite on StackShare](https://img.shields.io/badge/follow%20on-stackshare-blue?style=flat-square)](https://stackshare.io/appwrite)
+[![appwrite.io](https://img.shields.io/badge/appwrite-.io-f02e65?style=flat-square)](https://appwrite.io)
+
+A simple PHP Extension written in Rust to create scrypt password hashes. Supports building on X86-64 and ARM platforms.
 
 ## Installation
-Once you have a compiled version, either through a release or building it yourself, you can install the extension by moving it to your PHP extension directory which is usually `/usr/local/lib/php/extensions/`. on Linux and `C:\php\extensions` on Windows.
 
-Next you need to add the extension to your php.ini file.
+### Compiling Requirements
+- Linux, MacOS or Windows-based operating system
+- Latest Version of Rust Stable
+- PHP 8.0 or newer
+- Clang 5.0 or Later
+
+### Notes for Windows compilation
+- This extension can only be compiled for PHP installations sourced from https://windows.php.net.
+- Rust Nightly is required for Windows compilation.
+- This extension requires the `cl.exe` compiler. This is usually bundled with Visual Studio.
+- Stub generation does not work on Windows.
+
+### Building The Extension
+Clone the repository into your project directory.
+```bash
+git clone https://github.com/appwrite/php-scrypt.git && \
+cd php-scrypt
+```
+Compile the extension
+```bash
+cargo build --release
+```
+
+<details>
+<summary>
 
-MacOS:
-```php
-extension=libphp_scrypt.dylib
+### Building for Alpine
+
+</summary>
+While writing this extension we found out that [Rust in general](https://github.com/rust-lang/rust/issues/59302) still has a few issues with [musl libc](https://musl.libc.org/) found in Alpine. It is possible to build this project successfully by using an alternative linker and building on a gnu-based system targetting `linux-unknown-musl`.
+
+We strongly recommend using [zigbuild](https://github.com/messense/cargo-zigbuild) as the linker for this project as we found it's the most stable and easy to install alternate linker. we also use the "-C target-feature=crt-static" compiler flags to aid with building on musl as stated [here](https://github.com/rust-lang/rust/issues/59302).
+
+The build command for these platforms will look like so:
+```sh
+RUSTFLAGS="-C target-feature=-crt-static" cargo zigbuild --workspace --all-targets --target x86_64-unknown-linux-musl --release
 ```
+This will produce a .so file similar to a normal build.
+</details>
 
-Linux:
-```php
-extension=libphp_scrypt.so
+### Installing the Extension
+Copy the compiled extension from the `target` directory into your PHP extension directory.
+
+If you don't know where your PHP extension directory is you can run the following command:
+```bash
+php -i | grep extension_dir
 ```
 
-Windows:
-```php
-extension=libphp_scrypt.dll
+Copy the extension to the directory outputted
+```bash
+cp target/release/libphp-scrypt.so /path/to/extension_dir
 ```
 
-After that the extension will be available to you, check out **Usage** below to see how to use it.
+> Depending on your OS, your extension may end with `.dll` for windows or `.dylib` for macOS.
+
+### Enabling the extension
+
+After compiling and moving the extension into the correct directory, you can enable the extension by adding the following line to your `php.ini` file:
+
+```
+extension=libphp-scrypt.so
+```
+> Change .so to .dll for Windows or .dylib for macOS.
 
 ## Usage
 Using the scrypt extension is easy, there is only one function in this extension the usage is as follows:
@@ -41,25 +90,6 @@ $hash = \scrypt("password", "salt", 32768, 8, 1, 64);
 \var_dump("Your hash is " . $hash);
 ```
 
-## Building the extension
-Building this extension requires that you have a version of PHP installed that has the `php-config` command.
-
-After all the prequisites are met simply run the following command to build a release version of the extension:
-```sh
-cargo build --release
-```
-
-### Building for Alpine
-While writing this extension we found out that [Rust in general](https://github.com/rust-lang/rust/issues/59302) still has a few issues with [musl libc](https://musl.libc.org/) found in Alpine. It is possible to build this project successfully by using an alternative linker and building on a gnu-based system targetting linux-unknown-musl.
-
-We strongly recommend using [zigbuild](https://github.com/messense/cargo-zigbuild) as the linker for this project as we found it's the most stable and easy to install alternate linker. we also use the "-C target-feature=crt-static" compiler flags to aid with building on musl as stated [here](https://github.com/rust-lang/rust/issues/59302).
-
-The build command for these platforms will look like so:
-```sh
-RUSTFLAGS="-C target-feature=-crt-static" cargo zigbuild --workspace --all-targets --target x86_64-unknown-linux-musl --release
-```
-This will produce a .so file similar to a normal build.
-
 ## Authors
 
 **Bradley Schofield**
@@ -73,9 +103,15 @@ This will produce a .so file similar to a normal build.
 **Eldad Fux**
 -   [https://github.com/eldadfux](https://github.com/eldadfux)
 
-## Copyright and license
+## Special Thanks
+-  [davidcole1340](https://github.com/davidcole1340) -  For developing the [ext-php-rs](https://github.com/davidcole1340/ext-php-rs) bindings used for this project.
 
-The MIT License (MIT) [http://www.opensource.org/licenses/mit-license.php](http://www.opensource.org/licenses/mit-license.php)
+## Contributing
 
+All code contributions - including those of people having commit access - must go through a pull request and approved by a core developer before being merged. This is to ensure proper review of all the code.
 
+We truly ❤️ pull requests! If you wish to help, you can learn more about how you can contribute to this project in the [contribution guide](CONTRIBUTING.md).
+
+## Copyright and license
 
+The MIT License (MIT) http://www.opensource.org/licenses/mit-license.php
