Merge pull request #1 from locomotivemtl/develop

Refactor code base

.gitattributes

@@ -1,9 +1,9 @@
 # Ignore for "dist".
+/.github            export-ignore
 /build              export-ignore
 /tests              export-ignore
 /.editorconfig      export-ignore
 /.gitattributes     export-ignore
 /.gitignore         export-ignore
-/.travis.yml        export-ignore
 /phpcs.xml.dist     export-ignore
 /phpunit.xml.dist   export-ignore

.github/workflows/ci.yml

@@ -0,0 +1,125 @@
+name: CI
+
+on:
+  push:
+    branches:
+      - main
+    tags-ignore:
+      - '**'
+  pull_request:
+    branches:
+      - main
+    tags-ignore:
+      - '**'
+
+permissions:
+  contents: read
+
+defaults:
+  run:
+    shell: bash
+
+jobs:
+  run:
+    name: PHP ${{ matrix.php }}
+    runs-on: ubuntu-latest
+    strategy:
+      matrix:
+        php:
+          - '7.4'
+          - '8.0'
+    steps:
+      - name: Checkout project
+        uses: actions/checkout@v4
+
+      - name: Setup PHP
+        uses: shivammathur/setup-php@v2
+        with:
+          php-version: ${{ matrix.php }}
+          extensions: json, mbstring, pdo
+          coverage: xdebug
+          tools: composer, phpcs, phpstan, phpunit, psalm
+
+      - name: Validate Composer manifest
+        run: composer validate --strict
+
+      - name: Cache Composer packages
+        id: composer-cache
+        uses: actions/cache@v3
+        with:
+          path: vendor
+          key: ${{ runner.os }}-php-${{ matrix.php }}-composer-${{ hashFiles('**/composer.lock') }}
+
+      - name: Install Composer dependencies
+        id: composer-install
+        run: composer install --prefer-dist --no-progress --optimize-autoloader
+
+      - name: Lint (JSON)
+        id: lint-json
+        if: ${{ always() && steps.composer-install.conclusion == 'success' }}
+        # Depending on the runner/shell, output is piped differently
+        # between commands resulting in false-positive edge cases.
+        #
+        # The following script swallows the error raised when there
+        # are no JSON files in the repository to lint.
+        run: |
+          # composer lint:json
+          RESULTS=$( \
+            find {config,metadata} -type f -iname '*.json' -print0 2> /dev/null | \
+            xargs -0 ./vendor/bin/jsonlint -q 2>&1 > /dev/null \
+          ) || true
+
+          if [[ -n "$RESULTS" && $RESULTS != 'No file name or json input given' ]]; then
+            echo $RESULTS >&2
+            false
+          fi
+
+      - name: Lint (PHP)
+        id: lint-php
+        if: ${{ always() && steps.composer-install.conclusion == 'success' }}
+        # Depending on the runner/shell, output is piped differently
+        # between commands resulting in false-positive edge cases.
+        #
+        # The following script aggregates the output of all PHP file
+        # linting done in parallel.
+        run: |
+          # composer lint:php
+          RESULTS=$( \
+            find {src,tests} -type f -iname '*.php' -print0 2> /dev/null | \
+            xargs -0 -n1 -P8 php -l 2> /dev/null | \
+            grep -v '^No syntax errors detected' \
+          ) || true
+
+          if [[ -n "$RESULTS" ]]; then
+            echo $RESULTS >&2
+            false
+          fi
+
+      - name: Lint (PHPCS)
+        id: lint-phpcs
+        if: ${{ always() && steps.lint-php.conclusion == 'success' }}
+        run: phpcs -ps --colors --report-full src/
+
+      - name: Lint (PHPStan)
+        id: lint-phpstan
+        if: ${{ always() && steps.lint-php.conclusion == 'success' }}
+        run: phpstan analyse --no-progress --error-format=github
+
+      - name: Lint (Psalm)
+        id: lint-psalm
+        if: ${{ always() && steps.lint-php.conclusion == 'success' }}
+        run: psalm --no-progress --output-format=github
+
+      - name: Test (PHPUnit)
+        id: test-phpunit
+        if: ${{ always() && steps.lint-php.conclusion == 'success' }}
+        run: vendor/bin/phpunit --coverage-clover "var/reports/clover.xml" --coverage-text
+
+      # - name: Upload coverage results to Coveralls
+      #   id: coverage-coveralls
+      #   if: ${{ steps.test-phpunit.conclusion == 'success' }}
+      #   env:
+      #       COVERALLS_REPO_TOKEN: ${{ secrets.GITHUB_TOKEN }}
+      #   run: |
+      #       composer global require php-coveralls/php-coveralls
+      #       php-coveralls --coverage_clover=var/reports/clover.xml -v

CONTRIBUTING.md

@@ -0,0 +1,151 @@
+Contribution Guide
+==================
+
+Please take a moment to review this document in order to make the contribution
+process easy and effective for everyone involved.
+
+Following these guidelines helps to communicate that you respect the time of
+the developers managing and developing this open source project. In return,
+they should reciprocate that respect in addressing your issue or assessing
+patches and features.
+
+If you are tying to report a possible security vulnerability in Charcoal,
+please see our [security policy][SECURITY.md] for more information.
+
+Everyone interacting with Charcoal is expected to follow
+the [code of conduct][CODE_OF_CONDUCT.md].
+
+1. Charcoal utilizes coding conventions (indentation, comments, structures)
+   and adheres to PSR-1, PSR-3, PSR-4, PSR-6, PSR-7, PSR-11, PSR-12, and PSR-16.
+
+2. Charcoal is meant to be lean and fast with very few dependencies.
+   This means that not every feature request will be accepted.
+
+3. Charcoal has a minimum PHP version requirement of PHP 7.4.
+   Pull requests must not require a PHP version greater than PHP 7.4
+   unless the feature is only utilized conditionally and the file can
+   be parsed by PHP 7.4.
+
+4. All pull requests must include unit tests ([PHPUnit]) to ensure
+   the change works as expected and to prevent regressions.
+
+## Using the issue tracker
+
+The issue tracker is the preferred channel for [bug reports](#bug-reports),
+[features requests](#feature-requests) and [submitting pull requests](#pull-requests),
+but please respect the following restrictions:
+
+* Please **do not** use the issue tracker for personal support requests.
+* Please **do not** derail or troll issues. Keep the discussion on topic and
+  respect the opinions of others.
+
+## Bug reports
+
+A bug is a _demonstrable problem_ that is caused by the code in the repository.
+Good bug reports are extremely helpful — thank you!
+
+Guidelines for bug reports:
+
+1. **Use the central repository issue search** — 
+   Check if the issue has already been reported.
+
+2. **Check if the issue has been fixed** — 
+   Try to reproduce it using the latest `main`
+   or development branch in the repository.
+
+3. **Isolate the problem** — 
+   Make sure that the code in the repository
+   is _definitely_ responsible for the issue.
+
+A good bug report shouldn't leave others needing to chase you up for more
+information. Please try to be as detailed as possible in your report.
+
+## Feature requests
+
+Feature requests are welcome. But take a moment to find out whether your idea
+fits with the scope and aims of the project. It's up to *you* to make a strong
+case to convince the Charcoal developers of the merits of this feature. Please
+provide as much detail and context as possible.
+
+## Pull requests
+
+Good pull requests - patches, improvements, new features - are a fantastic help.
+They should remain focused in scope and avoid containing unrelated commits.
+
+**Please ask first** before embarking on any significant pull request (e.g.
+implementing features, refactoring code), otherwise you risk spending a lot of
+time working on something that the developers might not want to merge into the
+project.
+
+Adhering to the following this process is the best way to get your work merged:
+
+1. [Fork][gh-fork-repository] the repository, clone your fork,
+   and configure the remotes:
+
+   ```bash
+   # Clone your fork of the repository into the current directory
+   git clone https://github.com/<your-username>/<repo-name>
+   # Navigate to the newly cloned directory
+   cd <repo-name>
+   # Assign the original repository to a remote called "upstream"
+   git remote add upstream https://github.com/<upsteam-owner>/<repo-name>
+   ```
+
+2. If you cloned a while ago, get the latest changes from upstream:
+
+   ```bash
+   git checkout <dev-branch>
+   git pull upstream <dev-branch>
+   ```
+
+3. Create a new topic branch (off the main project development branch) to
+   contain your feature, change, or fix:
+
+   ```bash
+   git checkout -b <topic-branch-name>
+   ```
+
+4. Commit your changes in logical chunks. Please adhere to these
+   [git commit message guidelines][tbaggery.com-2008-04-19]
+   or your code is unlikely be merged into the main project.
+   Use Git's [interactive rebase][gh-rebase]
+   feature to tidy up your commits before making them public.
+
+5. Locally merge (or rebase) the upstream development branch into your topic branch:
+
+   ```bash
+   git pull [--rebase] upstream <dev-branch>
+   ```
+
+6. Push your topic branch up to your fork:
+
+   ```bash
+   git push origin <topic-branch-name>
+   ```
+
+10. [Open a Pull Request][gh-create-pull-request]
+    with a clear title and description.
+
+## Attribution
+
+This Contribution Guide is adapted from
+[Roots' Contribution Guide](https://github.com/roots/.github/blob/f33fd27/CONTRIBUTING.md)
+(version 2019-03-12) and
+[Guzzle's Contribution Guide](https://github.com/guzzle/guzzle/blob/84779a5/docs/overview.rst)
+(version 2022-07-31).
+
+[CODE_OF_CONDUCT.md]:      https://github.com/charcoalphp/.github/blob/main/CODE_OF_CONDUCT.md
+[gh-create-pull-request]:  https://help.github.com/articles/using-pull-requests/
+[gh-fork-repository]:      http://help.github.com/fork-a-repo/
+[gh-rebase]:               https://help.github.com/articles/interactive-rebase
+[PHPUnit]:                 https://github.com/sebastianbergmann/phpunit/
+[PSR-1]:                   https://www.php-fig.org/psr/psr-1/
+[PSR-3]:                   https://www.php-fig.org/psr/psr-3/
+[PSR-4]:                   https://www.php-fig.org/psr/psr-4/
+[PSR-6]:                   https://www.php-fig.org/psr/psr-6/
+[PSR-7]:                   https://www.php-fig.org/psr/psr-7/
+[PSR-11]:                  https://www.php-fig.org/psr/psr-11/
+[PSR-12]:                  https://www.php-fig.org/psr/psr-12/
+[PSR-16]:                  https://www.php-fig.org/psr/psr-16/
+[SECURITY.md]:             https://github.com/charcoalphp/.github/blob/main/SECURITY.md
+[tbaggery.com-2008-04-19]: http://tbaggery.com/2008/04/19/a-note-about-git-commit-messages.html