Skip to content

Contributing

We're excited that you're interested in contributing to this project! Collaboration is welcome and encouraged. Whether it's reporting a bug, discussing improvements, or submitting code changes, your help is valued.

Code of Conduct

Please note that this project is released with a Contributor Code of Conduct. By participating in this project, you agree to abide by its terms, available in the code of conduct file.

How to Contribute

We use GitHub Issues to track bugs, feature requests, documentation updates, and other tasks. We also use a GitHub Project board to visualize our workflow, plan upcoming work, and track progress on higher-level objectives.

  1. Find Work to Do:
    • Issues Tab: Browse individual tasks directly on the Issues tab. This is the primary list of all reported bugs, requested features, etc.
    • Project Board: Get a visual overview of our workflow, priorities, and what's currently in progress on our Project Board. The board organizes many of the items from the Issues tab into different stages (like Todo, In Progress, Done) and helps show our planned roadmap.
  2. Look for Labels: Whether viewing the Issues tab or the Project Board (where labels are often visible on cards), keep an eye out for:
    • good first issue: Specifically chosen as good starting points if you're new.
    • help wanted: Issues specifically marked as needing contributor help.
    • Other labels like bug, enhancement, documentation describe the type of work. (Tip: You can filter the issues list and sometimes the project board by labels!)
  3. Write Clear Issues (If Creating New Ones): If you're reporting a bug or suggesting a feature not already tracked, please create a new issue on the Issues tab and be as clear as possible. For bugs, include steps to reproduce, expected results, and actual results.
  4. Claim an Issue: If you find an existing issue you'd like to work on (either via the Issues tab or the Project Board), please navigate to the issue itself and leave a comment (e.g., "I'd like to work on this"). This helps avoid duplicated effort. A maintainer can then assign the issue to you.
  5. Work on Your Contribution:
    • Fork the repository to your own GitHub account.
    • Create a new branch for your changes (e.g., git checkout -b feature/add-new-widget or git checkout -b fix/login-bug).
    • Make your changes, adhering to the project's coding style and testing requirements (see sections below).
    • Commit your changes with clear commit messages.
    • Ensure your changes pass all relevant tests before submitting.
  6. Submit a Pull Request (PR):
    • Push your branch to your fork on GitHub.
    • Open a Pull Request back to the main repository (justincasher/vantage).
    • In the PR description, please link the issue you're addressing by including text like "Closes #123" or "Fixes #123" (replace 123 with the actual issue number). This automatically links the PR to the issue and helps project tracking.
    • Provide a clear description of the changes you've made.

Setting Up Your Development Environment

Please refer to the installation file for detailed instructions on how to clone the repository, install dependencies, and set up your local development environment.

Coding Style

Please ensure your code adheres to the guidelines outlined in the coding style guidelines file. This primarily involves following PEP 8 for formatting and Google Style for docstrings. Consistent code style helps maintain readability across the project.

Testing

Contributions should include relevant tests (unit or integration) where applicable. Before submitting a Pull Request, please ensure all tests pass. For details on the testing strategy and how to run tests, refer to the testing file.

Questions or Broader Discussions?

  • For questions related to a specific issue or Pull Request, please use the comment section directly on GitHub within that issue/PR.
  • For broader ideas, strategic discussions about the project's direction (which you might see reflected on the Project Board), or if you're unsure where to start and want to connect with the project lead, feel free to email Justin Asher directly at justinchadwickasher@gmail.com.

Thank you for considering contributing!