Merge pull request #56 from ConvertKit/1.0-docs

Add Guides and Documentation

Author: n7studios

.github/ISSUE_TEMPLATE/bug_report.yml

@@ -0,0 +1,70 @@
+name: Bug report
+description: Create a report to help us improve
+labels: ["bug"]
+body:
+  - type: markdown
+    attributes:
+      value: |
+        Thanks for taking the time to fill out this bug report!
+  - type: textarea
+    id: what-happened
+    attributes:
+      label: Describe the bug
+      description: A clear and concise description of what the bug is.
+      placeholder: Tell us what you see!
+    validations:
+      required: true
+  - type: textarea
+    id: repro-steps
+    attributes:
+      label: To Reproduce
+      description: Steps to reproduce the behavior
+      placeholder: |
+        1. Fetch a '...'
+        2. Update the '....'
+        3. See error
+    validations:
+      required: true
+  - type: textarea
+    id: expected-behavior
+    attributes:
+      label: Expected behavior
+      description: A clear and concise description of what you expected to happen.
+    validations:
+      required: true
+  - type: textarea
+    id: code-snippets
+    attributes:
+      label: Code snippets
+      description: If applicable, add code snippets to help explain your problem.
+      render: PHP
+    validations:
+      required: false
+  - type: input
+    id: os
+    attributes:
+      label: OS
+      placeholder: macOS
+    validations:
+      required: true
+  - type: input
+    id: language-version
+    attributes:
+      label: PHP version
+      placeholder: PHP 8.1
+    validations:
+      required: true
+  - type: input
+    id: lib-version
+    attributes:
+      label: Library version
+      placeholder: v1.0.0
+    validations:
+      required: true
+  - type: textarea
+    id: additional-context
+    attributes:
+      label: Additional context
+      description: Add any other context about the problem here.
+    validations:
+      required: false

.github/ISSUE_TEMPLATE/config.yml

@@ -0,0 +1,8 @@
+blank_issues_enabled: false
+contact_links:
+  - name: ConvertKit support
+    url: https://convertkit.com/support/
+    about: |
+      Please only file issues here that you believe represent actual bugs or feature requests for the ConvertKit PHP SDK.
+
+      If you're having general trouble with your ConvertKit integration, please reach out to support.

.github/ISSUE_TEMPLATE/feature_request.yml

@@ -0,0 +1,28 @@
+name: Feature request
+description: Suggest an idea for this PHP SDK
+labels: ["feature-request"]
+body:
+  - type: markdown
+    attributes:
+      value: |
+        Thanks for taking the time to fill out this feature request!
+  - type: textarea
+    id: problem
+    attributes:
+      label: Is your feature request related to a problem? Please describe.
+      description: A clear and concise description of what the problem is. Ex. I'm always frustrated when [...]
+  - type: textarea
+    id: solution
+    attributes:
+      label: Describe the solution you'd like
+      description: A clear and concise description of what you want to happen.
+  - type: textarea
+    id: alternatives
+    attributes:
+      label: Describe alternatives you've considered
+      description: A clear and concise description of any alternative solutions or features you've considered.
+  - type: textarea
+    id: context
+    attributes:
+      label: Additional context
+      description: Add any other context about the feature request here.

.github/docs/coding-standards.png

@@ -0,0 +1,11 @@
+# Contributing
+
+Contributions of any kind are welcome! If you've found a bug or have a feature request, please feel free to [open an issue](/issues). 
+
+To make changes yourself, follow these steps:
+
+1. Follow the [Setup Guide](SETUP.md) to set up your environment and clone this repository
+2. Follow the [Development Guide](DEVELOPMENT.md) to create a branch and make changes
+3. Refer to the [Testing Guide](TESTING.md) to write applicable unit tests and submit your pull request.
+
+Thanks!

.github/docs/new-release.png

@@ -0,0 +1,92 @@
+# Deployment Guide
+
+This document describes the workflow for deploying a PHP SDK update on GitHub.
+
+## Merge Pull Requests
+
+Merge the approved Pull Request(s) to the `main` branch.
+
+An *approved* Pull Request is when a PR passes all tests **and** has been approved by **one or more** reviewers.
+
+## Update the PHP SDK's Version Number
+
+We follow [Semantic Versioning](https://semver.org/).
+
+- In `src/ConvertKit_API.php`, change the `const VERSION` to the new version number.
+
+## Run phpDocumentor
+
+We use [phpDocumentor](https://www.phpdoc.org/) to automatically generate the [PHP SDK documentation](./docs/classes/ConvertKit_API/ConvertKit_API.md).
+
+In a Terminal window, run the phpDocumentor command to generate documentation in markdown format:
+
+```bash
+phpDocumentor --directory=src --target=docs --template="vendor/saggre/phpdocumentor-markdown/themes/markdown"
+```
+
+## Commit Changes
+
+Commit the updated files, which should comprise of:
+
+- `src/ConvertKit_API.php`
+- `docs/classes/ConvertKit_API/ConvertKit_API.md`
+
+## Create a New Release
+
+[Create a New Release](https://github.com/ConvertKit/convertkitsdk-php/releases/new), completing the following:
+
+- Choose a tag: Click this button and enter the new version number (e.g. `1.0`)
+- Release title: The version number (e.g. `1.0`)
+- Describe this release: Add a changelog detailing the applicable changes this version introduces, with a link to each PR, using the below template
+
+```
+# Deprecations / Notices
+
+- PHP: Minimum supported version is now `7.4`
+- `add_tag()` will trigger an `E_USER_NOTICE`, as the method name is misleading, and we prefer methods with named arguments; use `tag_subscribe()` (#44)
+- `form_subscribe()` will trigger an `E_USER_NOTICE`, as we prefer methods with named arguments; use `add_subscriber_to_form()` (#54)
+- `form_unsubscribe()` will trigger an `E_USER_NOTICE`, as the method name is misleading, and we prefer methods with named arguments; use `unsubscribe()` (#45)
+
+# Features / Additions
+
+- Added User-Agent on API requests (#34)
+- Added `get()`, `post()`, `put()` and `delete()` methods (#36)
+- Added `get_forms()` and `get_landing_pages()` methods (#41)
+- Added `get_form_subscriptions()` method (#42)
+- Added Tag methods `get_tags()`, `create_tag()`, `tag_subscriber()`, `remove_tag_from_subscriber()`, `remove_tag_from_subscriber_by_email()` (#44)
+- Added Subscriber methods `update_subscriber()`, `unsubscribe()` (#45)
+- Added `add_subscriber_to_sequence()` to support name, custom fields and tags (#43)
+- Added Custom Field methods `get_custom_fields()`, `add_custom_field()`, `add_custom_fields()`, `update_custom_field()`, `delete_custom_field()` (#46)
+- Added Purchase method `get_purchase()` (#47)
+- Added Webhook methods `create_webhook()`, `destroy_webhook() (#48)
+- Added Broadcast methods `create_broadcast()`, `get_broadcast()`, `get_broadcast_stats()`, `update_broadcast()`, `destroy_broadcast()`
+
+# Fixes / Improvements
+
+- Fixed: Guzzle version set to 6.5 or higher (#20, #26, #27)
+- Fixed: `get_subscriber_id()` performance (#21, #22, #29, #39)
+- Refactored: fetching legacy forms and landing pages (#32)
+- Refactored: using `api_version` property, API calls and logging (#37, #38)
+- Removed: Caching of resources and markup in class life cycle (#52)
+- Removed: `InvalidArgumentException` where type hints for methods now exist (#43)
+
+# Testing
+- Added PHPStan static analysis (#40)
+- Added PSR-12 coding standards with some modifications (#33)
+- Updated PHPUnit test coverage (#30, #35)
+```
+
+Generic changelog items such as `Fix: Various bugfixes` or `Several edge-case bug fixes` should be avoided.  They don't tell users (or us, as developers)
+what took place in this version.
+
+Each line in the changelog should start with `Added` or `Fix`.
+
+![New Release Screen](/.github/docs/new-release.png?raw=true)
+
+## Publish the Release
+
+When you're happy with the above, click `Publish Release`.
+
+This will then make the release available to developers, who can include it manually or using composer.
+
+The release will also be available to view on the [Releases](https://github.com/ConvertKit/convertkitsdk-php/releases) section of this GitHub repository.

.github/docs/phpstan.png

@@ -0,0 +1,56 @@
+# Development Guide
+
+This document describes the high level workflow used when working on the ConvertKit PHP SDK.
+
+You're free to use your preferred IDE and Git client.
+
+## Prerequisites
+
+If you haven't yet set up your local development environment with the ConvertKit PHP SDK repository installed, refer to the [Setup Guide](SETUP.md).
+
+## Create a Branch
+
+In your Git client / command line, create a new branch:
+- If this is for a new feature that does not have a GitHub Issue number, enter a short descriptive name for the branch, relative to what you're working on
+- If this is for a feature/bug that has a GitHub Issue number, enter issue-XXX, replacing XXX with the GitHub issue number
+
+Once done, make sure you've switched to your new branch, and begin making the necessary code additions/changes/deletions.
+
+## Coding Standards
+
+Code must follow [PSR-12 Coding standards](https://www.php-fig.org/psr/psr-12/), which is checked when running tests (more on this below).
+
+## Composer Packages
+
+We use Composer for package management.  A package can be added to one of two sections of the `composer.json` file: `require` or `require-dev`.
+
+### "require"
+
+Packages listed in the "require" directive are packages that the PHP SDK needs in order to function for end users.
+
+These packages are included when the PHP SDK release is published. 
+
+Typically, packages listed in this section would be libraries that the PHP SDK uses, such as:
+- [Guzzle](https://docs.guzzlephp.org/en/stable/): PHP HTTP Client
+- [Monolog](https://github.com/Seldaek/monolog): PSR-3 compatible logging client
+
+### "require-dev"
+
+Packages listed in the "require-dev" directive are packages that the PHP SDK **does not** need in order to function for end users.
+
+Typically, packages listed in this section would be internal development tools for testing, such as:
+- Coding Standards
+- PHPStan
+- PHPUnit
+
+## Committing Work
+
+Remember to commit your changes to your branch relatively frequently, with a meaningful, short summary that explains what the change(s) do.
+This helps anyone looking at the commit history in the future to find what they might be looking for.
+
+If it's a particularly large commit, be sure to include more information in the commit's description.
+
+## Next Steps
+
+Once you've finished your feature or issue, you must write/amend tests for it.  Refer to the [Testing Guide](TESTING.md) for a detailed walkthrough
+on how to write a test.