Merge pull request #208 from c0nst4ntin/improve-docs-and-contribution…

…-workflow

Improve Readme and Contribution Guide

.github/ISSUE_TEMPALTE/bug_report.md

@@ -0,0 +1,28 @@
+---
+name: 🚨 Bug report
+about: Report a bug to help improve the package.
+title: ""
+labels: "bug"
+assignees: ""
+---
+
+### Versions
+
+-   @prismic/sdk: <!-- ex: v5.3.0 -->
+-   php: <!-- ex: v8.3.12 -->
+
+### Reproduction
+
+<!-- If possible link to a minimal test case, without a reproduction, it is so hard to address problems -->
+
+### Steps to reproduce
+
+<!-- If possible, please provide exact steps to reproduce the issue. -->
+
+### What is expected?
+
+<!-- Please provide a clear and concise description of what you expected to happen. -->
+
+### What is actually happening?
+
+<!-- Please provide a clear and concise description of what actually happens. -->

.github/ISSUE_TEMPALTE/config.yml

@@ -0,0 +1,5 @@
+blank_issues_enabled: false
+contact_links:
+    - name: GitHub Discussions
+      url: https://github.com/prismicio-community/php-kit/discussions/new/choose
+      about: Ask a question about the package or raise an issue directly related the the package.

.github/ISSUE_TEMPALTE/feature_request.md

@@ -0,0 +1,23 @@
+---
+name: 🙋‍♀️ Feature request
+about: Suggest an idea or enhancement for the package.
+title: ""
+labels: "enhancement"
+assignees: ""
+---
+
+### Is your feature request related to a problem? Please describe.
+
+<!-- Please provide a clear and concise description of what the problem is. -->
+
+### Describe the solution you'd like
+
+<!-- Please provide a clear and concise description of what you want to happen. Adding some code examples would be neat! -->
+
+### Describe alternatives you've considered
+
+<!-- Please provide a clear and concise description of any alternative solutions or features you've considered. -->
+
+### Additional context
+
+<!-- Please add any other context or screenshots about the feature request here. -->

CONTRIBUTING.md

@@ -0,0 +1,64 @@
+# Contributing
+
+This package is primarily maintained by the community. External contributions are always welcome. If you need assistance, feel free to [open an issue](https://github.com/prismicio-community/php-kit/issues/new/choose) or request a review by opening a pull request.
+
+## Setup
+
+To get started working on this project, you’ll need the following set up on your local machine:
+
+-   PHP 8.0+
+-   Composer 2.0+
+-   The [APCu](https://www.php.net/manual/en/ref.apcu.php) extension for PHP
+
+Clone this GitHub repository, then run the following command to install all dependencies:
+
+```bash
+$ composer install
+```
+
+## Project-specific Notes
+
+Some of the SDK’s tests require APCu (Alternative PHP Cache) to function correctly from the command line. If you have APC installed and enabled, but cache-related tests still fail, please try the following:
+
+-   **Verify APC is enabled for CLI:** Run `php -i | grep apc` to check if APC is active for the command line. If no output appears, APC may be enabled only for the web server (e.g., Apache) and not for CLI. Consult your OS documentation to enable APC for CLI. If it involves modifying a `php.ini` file, ensure you're editing the correct one, as there may be separate `php.ini` files for the web server and CLI.
+
+-   **Enable the `apc.enable_cli` setting:** If APC is enabled for CLI but tests still fail, verify that `apc.enable_cli` is set to ‘On’ in the output of `php -i | grep apc`. If it isn’t, add `apc.enable_cli = 1` at the end of the appropriate `php.ini` file. Again, confirm you are editing the correct `php.ini` file for CLI, not the one used by Apache.
+
+## Develop
+
+Once your environment is set up, you can start developing new features or fixing bugs. Please ensure that you follow the coding standards and conventions in the existing codebase.
+
+Before starting on a large change, it’s recommended that you open an issue to discuss your proposed changes. This allows you to receive early feedback and helps determine the best way to proceed.
+
+If you want to test your changes in an example you can either create a new file in the `samples` directory or modify an existing one (locally). In case you want to test the changes in a real project, you can link your local package to the project using [Composer](https://getcomposer.org/doc/05-repositories.md#path).
+
+In any case please make sure to write test cases for your changes.
+
+**Useful commands:**
+
+| Command             | Description                                                                      |
+| ------------------- | -------------------------------------------------------------------------------- |
+| `composer test`     | This command will run the test suite with PHPUnit (requires the APCu extension). |
+| `composer cs-check` | This command will check the code style with PHP CS Fixer.                        |
+
+## Tests
+
+Please ensure that you write tests for any new features or bug fixes you implement.
+
+If you find existing code that could benefit from additional testing, we appreciate contributions to improve test coverage. In such cases, please create a dedicated branch and submit a separate pull request to document and review your testing improvements.
+
+You can run the tests with the following command:
+
+```bash
+$ ./vendor/bin/phpunit
+```
+
+## Submit a pull request
+
+When you are ready to submit your changes, push your branch to the repository and open a pull request. Please include a detailed description of your changes and any relevant information for reviewers.
+
+Your pull request will be reviewed by a maintainer. If changes are requested, please make them on your branch and push the updates to the repository. The pull request will be updated automatically.
+
+## Publish
+
+Publishing a new version of the package is restricted to maintainers.

LICENSE

@@ -1,5 +1,13 @@
-Copyright 2018 Prismic (https://prismic.io).
+Copyright 2013-2024 Prismic <[email protected]> (https://prismic.io)
 
-Licensed under the Apache License, Version 2.0 (the "License"); you may not use this project except in compliance with the License. You may obtain a copy of the License at http://www.apache.org/licenses/LICENSE-2.0.
+Licensed under the Apache License, Version 2.0 (the "License");
+you may not use this file except in compliance with the License.
+You may obtain a copy of the License at
 
-Unless required by applicable law or agreed to in writing, software distributed under the License is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the License for the specific language governing permissions and limitations under the License.
+    http://www.apache.org/licenses/LICENSE-2.0
+
+Unless required by applicable law or agreed to in writing, software
+distributed under the License is distributed on an "AS IS" BASIS,
+WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+See the License for the specific language governing permissions and
+limitations under the License.

README.md

@@ -1,22 +1,43 @@
+# Prismic.io PHP SDK
+
 [![Github Actions CI][github-actions-ci-src]][github-actions-ci-href]
+[![Total Downloads][packagist-downloads-src]][packagist-downloads-href]
+[![Latest Stable Version][packagist-version-src]][packagist-version-href]
+[![License][packagist-license-src]][packagist-license-href]
 
-# PHP development kit for Prismic
+This is the official PHP SDK for Prismic.io, providing a straightforward way to connect to Prismic’s headless API. It is maintained by the community to help developers get started with Prismic in PHP.
 
-## Getting started
+-   Offers an easy-to-use interface for basic interactions with Prismic content
+-   Covers core features of the Prismic API
+
+### Overview
+
+1. [Getting started](#getting-started)
+    1. [Installation](#installation)
+    2. [Recommended PHP Extensions](#recommended-php-extensions)
+    3. [Basic Usage & API calls](#basic-usage--api-calls)
+    4. [DOM Helper](#dom-helper)
+2. [More information](#more-information)
+3. [Contributing](#contributing)
+4. [License](#license)
 
-### Install the kit for your project
+## Getting started
 
-First of all, install [APCu](https://www.php.net/manual/en/ref.apcu.php) to have the default built-in cache support.
+### Installation
 
-Install with [Composer](https://getcomposer.org/doc/00-intro.md):
+Installation using [Composer](https://getcomposer.org/doc/00-intro.md):
 
 ```bash
 $ composer require prismic/php-sdk
 ```
 
-### Usage
+### Recommended PHP Extensions
+
+We recommend installing and enabeling the [APCu](https://www.php.net/manual/en/ref.apcu.php) extension to have the built-in default cache support. Otherwise, you can implement your own cache strategy by extending the `Prismic\Cache\CacheInterface` interface.
 
-Include the dependency:
+### Basic Usage & API calls
+
+If you are not using automatic autoloading, include the Composer autoload file:
 
 ```php
 <?php
@@ -25,28 +46,26 @@ include_once __DIR__.'/../vendor/autoload.php';
 use Prismic\Api;
 ```
 
-Then call the API:
+Then you can start making your first API calls:
 
 ```php
-<?php
 $api = Api::get('https://your-repo-name.prismic.io/api/v2');
-$doc = $api->getByUID('get-started-type', 'get-started');
+$document = $api->getByUID('get-started-type', 'get-started');
 ```
 
-This kit supports PHP version >= 8.0
+### DOM Helper
 
-### DOM helpers usage
+The PHP SDK provides a set of DOM helpers to help you render your Prismic content.
 
-In these examples we have a $doc variable corresponding to the fetched Prismic document.
-We also have a $linkResolver variable containing the functional link resolver, [read our docs to learn more about Link Resolving](https://prismic.io/docs/php/beyond-the-api/link-resolving).
+In these examples we have a document variable corresponding to the fetched Prismic document. We also have a $linkResolver variable containing the functional link resolver, [read our docs to learn more about Link Resolving](https://prismic.io/docs/php/beyond-the-api/link-resolving).
 
 #### Link
 
 ```php
 <?php
 use Prismic\Dom\Link;
 
-echo Link::asUrl($doc->data->link, $linkResolver);
+echo Link::asUrl($document->data->link, $linkResolver);
 ```
 
 #### Rich Text
@@ -55,8 +74,8 @@ echo Link::asUrl($doc->data->link, $linkResolver);
 <?php
 use Prismic\Dom\RichText;
 
-echo RichText::asText($doc->data->title);
-echo RichText::asHtml($doc->data->description, $linkResolver);
+echo RichText::asText($document->data->title);
+echo RichText::asHtml($document->data->description, $linkResolver);
 ```
 
 #### Date
@@ -65,51 +84,61 @@ echo RichText::asHtml($doc->data->description, $linkResolver);
 <?php
 use Prismic\Dom\Date;
 
-$date = Date::asDate($doc->data->date);
+$date = Date::asDate($document->data->date);
 echo $date->format('Y-m-d H:i:s');
 ```
 
 ## More information
 
--   [Developer docs](./docs)
--   [PHP Quickstart tutorial](https://prismic.io/quickstart#?lang=php)
--   [PHPDoc](https://prismicio-community.github.io/php-kit/)
+-   [Developer Documentaiton](./docs)
+-   [Generated PHPDoc](https://prismicio-community.github.io/php-kit/)
 -   [Changelog](https://github.com/prismicio-community/php-kit/releases)
 
-## Install the kit locally
+## Contributing
 
-Clone this GitHub repository, then [install Composer](https://getcomposer.org/doc/00-intro.md) if you haven't, and run:
+Whether you're helping us fix bugs, improve the docs, or spread the word, we'd love to have you as part of the Prismic developer community!
 
-```bash
-$ composer install
-```
+**Reporting a bug**: [Open an issue][repo-bug-report] explaining your application's setup and the bug you're encountering.
 
-## Tests
+**Suggesting an improvement**: [Open an issue][repo-feature-request] explaining your improvement or feature so we can discuss and learn more.
 
-Please write tests for any bugfix or new feature.
+**Submitting code changes**: For small fixes, feel free to [open a pull request][repo-pull-requests] with a description of your changes. For large changes, please first [open an issue][repo-feature-request] so we can discuss if and how the changes should be implemented.
 
-If you find existing code that is not optimally tested and wish to make it better, we really appreciate it; but you should document it on its own branch and its own pull request.
+For more clarity on this project, check out the detailed [CONTRIBUTING.md](./CONTRIBUTING.md) for our guidelines.
 
-Tests are run by running the command:
+## License
 
-```bash
-$ ./vendor/bin/phpunit
-```
+This software is licensed under the [Apache 2 License](https://opensource.org/license/apache-2-0), quoted below:
 
-Some of the kit's tests check stuff that are built on top of APC and need APC to work from the command line. If you've installed and enabled APC, and your cache tests don't pass:
+```plaintext
+Copyright 2013-2024 Prismic <[email protected]> (https://prismic.io)
 
--   check if your APC is enabled for your command line, by running `php -i | grep apc`; if no output is displayed, then maybe the APC extension you installed and enabled is only enabled in apache but not for your command line. Check how your OS works to make that happen, and if it involves changing a php.ini file, make sure it's the right php.ini (you might have one for apache, and one for the command line)
--   if APC is enabled for the command line, and yet the tests still fail, make sure your `apc.enable_cli` (which you see in the output of `php -i | grep apc`) is 'On'. If it's not, add this at the end of your php.ini: `apc.enable_cli = 1`. Make sure it's the right php.ini (you might have one for apache, and one for the command line)
+Licensed under the Apache License, Version 2.0 (the "License");
+you may not use this file except in compliance with the License.
+You may obtain a copy of the License at
 
-## License
+    http://www.apache.org/licenses/LICENSE-2.0
 
-This software is licensed under the Apache 2 license, quoted below.
+Unless required by applicable law or agreed to in writing, software
+distributed under the License is distributed on an "AS IS" BASIS,
+WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+See the License for the specific language governing permissions and
+limitations under the License.
+```
 
-Copyright 2018 Prismic (https://prismic.io).
+<!-- Links -->
 
-Licensed under the Apache License, Version 2.0 (the "License"); you may not use this project except in compliance with the License. You may obtain a copy of the License at http://www.apache.org/licenses/LICENSE-2.0.
+[repo-bug-report]: https://github.com/prismicio-community/php-kit/issues/new?assignees=&labels=bug&template=bug_report.md&title=
+[repo-feature-request]: https://github.com/prismicio-community/php-kit/issues/new?assignees=&labels=enhancement&template=feature_request.md&title=
+[repo-pull-requests]: https://github.com/prismicio-community/php-kit/pulls
 
-Unless required by applicable law or agreed to in writing, software distributed under the License is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the License for the specific language governing permissions and limitations under the License.
+<!-- Badges -->
 
 [github-actions-ci-src]: https://github.com/prismicio-community/php-kit/workflows/ci/badge.svg
 [github-actions-ci-href]: https://github.com/prismicio-community/php-kit/actions?query=workflow%3Aci
+[packagist-downloads-src]: https://img.shields.io/packagist/dm/prismic/php-sdk
+[packagist-downloads-href]: https://packagist.org/packages/prismicio-community/php-kit
+[packagist-version-src]: https://img.shields.io/packagist/v/prismic/php-sdk
+[packagist-version-href]: https://packagist.org/packages/prismicio-community/php-kit
+[packagist-license-src]: https://img.shields.io/packagist/l/prismic/php-sdk
+[packagist-license-href]: https://packagist.org/packages/prismicio-community/php-kit