Contributing to EspnApiSymfonyBundle

First off, thanks for taking the time to contribute!

The following is a set of guidelines for contributing to EspnApiSymfonyBundle. These are mostly guidelines, not rules. Use your best judgment, and feel free to propose changes to this document in a pull request.

Code of Conduct

This project and everyone participating in it is governed by the Symfony Code of Conduct. By participating, you are expected to uphold this code. Please report unacceptable behavior to bjoern.may@gmail.com.

I don’t want to read this whole thing I just have a question!!!

Note

Please don’t file an issue to ask a question. You’ll get faster results by using the resources below.

  • For questions about the raw ESPN data, consult the unofficial community documentation of the ESPN API — ESPN publishes no official docs for these endpoints.

  • For questions about fetching data, see the espn-api-client documentation; this bundle only builds on top of it.

  • For questions about this bundle (entities, importers, the message chain), prefer a discussion thread over an issue.

How Can I Contribute?

Reporting Bugs

This section guides you through submitting a bug report for EspnApiSymfonyBundle. Following these guidelines helps maintainers and the community understand your report, reproduce the behavior, and find related reports.

When you are creating a bug report, please include as many details as possible.

Note

If you find a Closed issue that seems like the same thing you’re experiencing, open a new issue and include a link to the original issue in the body of your new one.

How Do I Submit A (Good) Bug Report?

Bugs are tracked as GitHub issues. Create an issue on the repository and provide the following information.

Explain the problem and include additional details to help maintainers reproduce the problem:

  • Use a clear and descriptive title for the issue to identify the problem.

  • Describe the exact steps which reproduce the problem in as many details as possible. Which message did you dispatch, with which reference and import-control array? When listing steps, don’t just say what you did, but explain how you did it.

  • Provide specific examples to demonstrate the steps. Include the dispatched message, the reference URL, and (a trimmed copy of) the ESPN JSON if relevant, in Markdown code blocks.

  • Describe the behavior you observed and point out what exactly is the problem with that behavior. Include the relevant log lines — the bundle logs import failures with the offending reference.

  • Explain which behavior you expected to see instead and why.

Provide more context by answering these questions:

  • Did the problem start happening recently (e.g. after updating the bundle) or was this always a problem?

  • If the problem started happening recently, can you reproduce the problem in an older version? What’s the most recent version in which it doesn’t happen?

  • Can you reliably reproduce the issue? If not, provide details about how often it happens and under which conditions. Bear in mind the ESPN API is itself occasionally inconsistent, and that import order matters (a child dispatched before its parent will fail).

Include details about your configuration and environment:

  • Which version of EspnApiSymfonyBundle and espn-api-client are you using?

  • Which Symfony and PHP versions are you using?

  • Which database platform and version? (Some entities use JSON columns, decimals, and join tables.)

  • How is Messenger configured — which transports, routing, and retry strategy?

Suggesting Enhancements

This section guides you through submitting an enhancement suggestion for EspnApiSymfonyBundle, including completely new features and minor improvements to existing functionality.

When you are creating an enhancement suggestion, please include as many details as possible.

How Do I Submit A (Good) Enhancement Suggestion?

Enhancement suggestions are tracked as GitHub issues. Create an issue on the repository and provide the following information:

  • Use a clear and descriptive title for the issue to identify the suggestion.

  • Provide a step-by-step description of the suggested enhancement in as many details as possible.

  • Provide specific examples to demonstrate the steps, in Markdown code blocks.

  • Describe the current behavior and explain which behavior you expected to see instead and why.

  • Explain why this enhancement would be useful to most users and isn’t something better implemented in a consuming application.

  • Specify which version of the bundle you’re using.

Pull Requests

The process described here has several goals:

  • Maintain EspnApiSymfonyBundle’s quality

  • Fix problems that are important to users

  • Engage the community in working toward the best possible bundle

  • Enable a sustainable system for maintainers to review contributions

Please follow these steps to have your contribution considered by the maintainers:

  1. Formulate what your pull request is intended to do.

  2. Follow the styleguides.

  3. When adding a resource, include all of its layers in the same pull request — entity, repository, converter, importer, message, and handler — plus the service registrations and the messenger routing. See Extending.

  4. Respect the layering: converters set only scalars and references; importers own all entity-to-entity connections.

  5. Cover new behavior with tests where practical.

While the prerequisites above must be satisfied prior to having your pull request reviewed, the reviewer(s) may ask you to complete additional tests or other changes before your pull request can be ultimately accepted.

Styleguides

Git Commit Messages

  • Use the present tense (“Add feature” not “Added feature”)

  • Use the imperative mood (“Move cursor to…” not “Moves cursor to…”)

  • Limit the first line to 72 characters or less

  • Reference issues and pull requests liberally after the first line

PHP Styleguide

Stick to:

In addition, follow the bundle’s established conventions:

  • Entities use espnId, bigint identity keys, nullable columns, the SyncTimestampsTrait, and enums for fixed vocabularies.

  • Free-form text columns are TEXT, not VARCHAR(255).

  • Converters set scalars and reference strings only; importers perform all entity connections, from the owning side of an association.

  • Handlers persist exactly the entity their importer returns, then dispatch children gated by shouldImport().

  • Use UnrecoverableImportException for permanent failures and a plain ImportException (or other \Throwable) for retryable ones.

  • Columns that collide with SQL reserved words are mapped to a safe column name explicitly.

Documentation Styleguide

  • Use reStructuredText and remain compatible with Read the Docs.

  • Every deep-dive topic lives in its own file and is linked from index.rst through the toctree.