Skip to content

CONTRIBUTING.md

Latest commit

 

History

History
207 lines (126 loc) · 8.75 KB

CONTRIBUTING.md

File metadata and controls

207 lines (126 loc) · 8.75 KB

Contributing to the NBA_API

Welcome, and thank you for your interest in contributing to the NBA_API!

There are many ways in which you can contribute, beyond writing code. The goal of this document is to provide a high-level overview of how you can get involved.

Asking Questions

Have a question? Rather than opening an issue, head over to the Slack to connect with others, chat, and receive help.

Reporting Issues

Have you identified a reproducible problem? Have a feature request? Identified a missing endpoint? Here's how you can make reporting your issue as effective as possible.

Look For an Existing Issue

Before you create a new issue, please do a search in open issues to see if the issue or feature request has already been filed.

If you find your issue already exists, make relevant comments and add your reaction. Use a reaction in place of a "+1" comment:

  • 👍 - upvote
  • 👎 - downvote

If you cannot find an existing issue that describes your bug or feature, create a new issue using the guidelines below.

Writing Good Bug Reports and Feature Requests

File a single issue per problem and feature request. Do not enumerate multiple bugs or feature requests in the same issue.

Do not add your issue as a comment to an existing issue unless it's for the identical input. Many issues look similar, but have different causes.

The more information you can provide, the more likely someone will be successful at reproducing the issue and finding a fix.

Please include the following with each issue:

  • Version of the nba_api you are using

  • Reproducible steps (1... 2... 3...) that cause the issue

  • What you expected to occur, versus what you actually occur

  • A code snippet that demonstrates the issue or a link to a code repository that can easily be pull down to recreate the issue locally

    • Note: Because the developers need to copy and paste the code snippet, including a code snippet as a media file (i.e. .gif) is not sufficient.

Final Checklist

Please remember to do the following:

  • Search the issue repository to ensure your report is a new issue

  • Recreate the issue

  • Simplify your code around the issue to better isolate the problem

Contributing Code

The nba_api project has been setup in a way to support development across a wide range of operating systems including Linux, macOS, and Windows. Contributions are managed via GitHub forks and pull requests.

Style Guidelines

  • Code submitted should follow the style of the code already found throughout the repository.
  • The structure of data returned to the consumer of the library should align with the data structures already found throughout the library.
  • Unit tests should accompany your code wherever possible
  • Use git rebase -i to organize your commits (Write Better Commits, Build Better Projects)

Commit Message Format

This project uses Conventional Commits for automated changelog generation and semantic versioning. Please format your commit messages as follows:

<type>[optional scope]: <description>

[optional body]

[optional footer(s)]

Commit Types

  • feat: A new feature (triggers minor version bump)
  • fix: A bug fix (triggers patch version bump)
  • docs: Documentation only changes
  • style: Changes that do not affect the meaning of the code
  • refactor: A code change that neither fixes a bug nor adds a feature
  • perf: A code change that improves performance
  • test: Adding missing tests or correcting existing tests
  • build: Changes that affect the build system or external dependencies
  • ci: Changes to CI configuration files and scripts
  • chore: Other changes that don't modify src or test files

Examples

feat: add new endpoint for player statistics
fix: resolve timeout issue in HTTP requests
docs: update API documentation for new endpoints

Breaking Changes: Add BREAKING CHANGE: in the commit body or add ! after the type to trigger a major version bump:

feat!: remove deprecated endpoint support

Collaborating on Open Source

Proposals

Should you wish to make a significant change within the project, please open a GitHub Issue using the prefix PROPOSAL: within the subject.

Code Reviews

GitHub allows developers the ability to draft pull requests. This is incredibly useful to get feedback early within the development cycle when making large or complex changes.

Requirements

Python Supported Versions

Supported versions can be found within the build script.

While nba_api makes every attempt to provide compatibility with Supported Versions of Python, libraries that the nba_api depends on may not offer that same compatibility. Should this occur, the nba_api will support the next Supported Version of Python in which all libraries share mutual compatibility.

Poetry

Development on nba_api requires Poetry. Poetry provides environment isolation managing all dependencies and packaging in a deterministic way.

pyenv (optional)

The nba_api project supports pyenv and includes a poetry.lock file to recognize the currently active environment.

[virtualenvs]
prefer-active-python = true

Setting up your environment

This guide assumes familiarity with using GitHub and git.

1. Install and configure pyenv (optional)

Follow the pyenv installation instructions.

2. Install Poetry

Follow the Poetry installation instructions.

3. Fork the nba_api

Follow GitHub's instructions on how to fork a repository and clone that repository for local development.

4. Using Poetry with nba_api

# Create a isolated virtual environment inclusive of all dependencies
poetry install

# Once the environment has been created, activate the environment for development
eval $(poetry env activate)

5. Set Up Pre-Commit Hooks

This project uses pre-commit to automatically lint and format code before each commit using Ruff.

# Install the git hooks (only needed once per clone)
pre-commit install

Once installed, ruff will automatically fix imports, formatting, and style issues on every git commit. If files are modified by the hooks, re-stage them and commit again.

6. Validating Your Environment

Poetry provides all of the developer dependencies through the pyproject.toml file. This allows you to begin using the required development tools immediately.

# Run unit tests (all tests should pass)
pytest

# Lint and auto-fix with Ruff
ruff check src/ --fix

# Format with Ruff
ruff format src/

7. When Complete, Open a PR

When you have completed your development and uploaded your changes to GitHub, create a pull request to have your changes reviewed.

Release Automation

This project uses automated releases based on conventional commit messages. When PRs are merged to the master branch, the system automatically:

  • Determines the appropriate version bump (patch/minor/major)
  • Updates the changelog
  • Creates a git tag
  • Publishes to PyPI
  • Creates a GitHub release

Testing Release Changes

If your changes affect the release process or you want to test automation:

  • For maintainers: See RELEASE_TESTING.md for safe testing methods
  • For contributors: Follow the conventional commit format - the automation will handle the rest

The conventional commit format ensures your changes are properly categorized for automatic version management.