Contributing

ShopClass is maintained by its users. Contributions are welcome: bug fixes, features, translations and documentation. Several of the most useful ones need no PHP at all.

Code

1. Open an issue first, describing the change. It is much less painful to agree an approach before the work than after it.
2. Branch from develop. Never target master.
3. Make the change. After cloning, run composer install and npm ci && npm run build once. Generated files are not committed.
4. Run composer test, composer test:models and composer lint, and the other checks in tests/README.md.
5. Open a pull request against develop.

See coding style for the standard, and the developer overview for a local development stack.

Generated files are not in git

oc-includes/vendor/, oc-includes/assets/ (except assets/osclass/) and the admin CSS and JS are built by composer install and npm run build. CI builds them for release zips.

Running the tests

npm run test:db                  # a throwaway MySQL on 127.0.0.1:33061 (Docker)
composer test                    # the unit tests, 4 at a time
composer test:models             # the database tests

Both suites need that database: some unit tests make a scratch database of their own.

How to write a test, the pinned lists and every check CI runs are in tests/README.md.

Documentation

These pages live in the ShopClass repository under docs/site/ and are published to this site automatically. Every page has an Edit this page link at the bottom that takes you straight to the file on GitHub.

Documentation is the easiest first contribution, and the most useful one to someone stuck at 2am: a hosting quirk you worked around, a step that was missing, an error message nobody had written down.

Translations

Translations live in mindstellar/shopclass-i18n. Fixing an awkward string in a language you speak is a real contribution, and takes minutes.

Testing

You do not have to write code to help. Running a prerelease against a real site, your own copy, not production, and reporting what broke is genuinely valuable, and it is how compatibility problems get found before a release instead of after.

Reporting bugs and suggesting features

Open an issue. A reproducible report is worth ten vague ones: see how to write a bug report.

Security vulnerabilities are the exception: do not open a public issue. The security policy explains how to report them privately.

Helping other people

Questions and discussion happen in GitHub Discussions. Answering someone else’s question is a contribution, and often a better use of an hour than writing code.

Plugins and themes

Publishing an extension helps the whole ecosystem, and, unlike core, it is entirely yours. See the market.

Telling people

More users means a stronger community means a better ShopClass. A link, a mention, a blog post about what you built with it: all of it counts.