add contributors guidlines

CODE_OF_CONDUCT.md

@@ -68,9 +68,9 @@ 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
+available at [https://www.contributor-covenant.org/version/1/4/code-of-conduct.html](https://www.contributor-covenant.org/version/1/4/code-of-conduct.html)
 
-[homepage]: https://www.contributor-covenant.org
+[homepage]: [https://www.contributor-covenant.org](https://www.contributor-covenant.org)
 
 For answers to common questions about this code of conduct, see
-https://www.contributor-covenant.org/faq
+[https://www.contributor-covenant.org/faq](https://www.contributor-covenant.org/faq)

CONTRIBUTING.md

@@ -0,0 +1,75 @@
+# Contributing to the PHP Standard Library
+
+Thank you for contributing to the PHP Standard Library!
+
+## Code of Conduct
+
+The code of conduct is described in [CODE_OF_CONDUCT.md](./CODE_OF_CONDUCT.md)
+
+## Issues
+
+We use GitHub issues to track issues within PSL.
+
+Please ensure your description is clear and has sufficient instructions to be able to reproduce the issue.
+
+## Submitting Pull Requests
+
+Before we can merge your Pull-Request here are some guidelines that you need to follow.
+
+These guidelines exist not to annoy you, but to keep the code base clean, unified and future proof.
+
+### Principles
+
+- All functions should be typed as strictly as possible
+- The library should be internally consistent
+- References may not be used
+- Arguments should be as general as possible. For example, for `array` functions, prefer `iterable` inputs where practical, falling back to `array` when needed.
+- Return types should be as specific as possible
+- All files should contain `declare(strict_types=1);`
+
+### Consistency Rules
+
+This is not exhaustive list.
+
+- Functions argument order should be consistent within the library
+  - All iterable-related functions take the iterable as the first argument ( e.g. `Dict\map` and `Dict\filter` )
+  - `$haystack`, `$needle`, and `$pattern` are in the same order for all functions that take them
+- Functions should be consistently named.
+- If an operation can conceivably operate on either keys or values, the default is to operate on the values - the version that operates on keys should have `_key` suffix (e.g. `Iter\last`, `Iter\last_key`, `Iter\contains`, `Iter\contains_key` )
+- Iterable functions that do an operation based on a user-supplied keying function for each element should be suffixed with `_by` (e.g. `Vec\sort_by`, `Dict\group_by`, `Math\max_by`)
+
+### Tests
+
+PSL tries to maintain a 100% code coverage, meaning everything within the library *MUST* be tested.
+
+If you are submitting a bug-fix, please add a test case to reproduce the bug.
+If you are submitting a new feature, please make sure to add tests for all possible code paths.
+
+To run the tests, use `make unit-tests`.
+
+### Code Style
+
+PSL follows a custom set of rules that extend PSR-12, PSR-2, and PSR-1.
+
+To check if your code contains any issues that violate PSL rules, use `make coding-standard-check`.
+
+You may fix many of the issues using `make coding-standard-fix`.
+
+### Static Analysis
+
+PSL uses Psalm static analysis tool to avoid type issues within the code base, and to provide a better API
+for the end user.
+
+PSL is configured to pass the strictest psalm level.
+
+To ensure that your code doesn't contain any type issues, use `make type-check`.
+
+To ensure that your code doesn't introduce any security issues, use `make security-analysis`
+
+### License
+
+By contributing to the PHP Standard Library ( PSL ), you agree that your contributions will be licensed under the [LICENSE](./LICENSE) file in the root directory of this source tree.
+
+## Security Disclosures
+
+You can read more about how to report security issues in our [Security Policy](./SECURITY.md).

README.md

@@ -54,27 +54,11 @@ Please refer to the [`php-standard-library/psalm-plugin`](https://github.com/php
 
 ## Documentation
 
-You can read through the API documentation in [`docs/README.md`](./docs/README.md).
+You can read through the API documentation in [`docs/`](./docs) directory.
 
-## Principles
+## Interested in contributing?
 
-- All functions should be typed as strictly as possible
-- The library should be internally consistent
-- References may not be used
-- Arguments should be as general as possible. For example, for `array` functions, prefer `iterable` inputs where practical, falling back to `array` when needed.
-- Return types should be as specific as possible
-- All files should contain `declare(strict_types=1);`
-
-## Consistency Rules
-
-This is not exhaustive list.
-
-- Functions argument order should be consistent within the library
-  - All iterable-related functions take the iterable as the first argument ( e.g. `Iter\map` and `Iter\filter` )
-  - `$haystack`, `$needle`, and `$pattern` are in the same order for all functions that take them
-- Functions should be consistently named.
-- If an operation can conceivably operate on either keys or values, the default is to operate on the values - the version that operates on keys should have `_key` suffix (e.g. `Iter\last`, `Iter\last_key`, `Iter\contains`, `Iter\contains_key` )
-- Iterable functions that do an operation based on a user-supplied keying function for each element should be suffixed with `_by` (e.g. `Arr\sort_by`, `Iter\group_by`, `Math\max_by`)
+Have a look at [`CONTRIBUTING.md`](./CONTRIBUTING.md).
 
 ## Sponsors
 

SECURITY.md

@@ -4,4 +4,4 @@ If you discover a security vulnerability within PSL, please send an e-mail to Sa
 
 Please withhold public disclosure until after we have addressed the vulnerability.
 
-There are no hard and fast rules to determine if a bug is worth reporting as a security issue. 
+There are no hard and fast rules to determine if a bug is worth reporting as a security issue.