Skip to content

Contributing

Code Explanation

A step-by-step guide for contributing to our open-source Python app. It includes instructions for forking the repository, cloning it, creating a new branch, making changes, committing those changes, pushing them to GitHub, and finally creating a pull request. The guidelines section emphasizes following the PEP 8 style guide, documenting code, and ensuring tests are run.

Algorithmic Approach:

  1. Fork Repository: Create a personal copy of the repository on GitHub.
  2. Clone Repository: Download the repository to your local machine.
  3. Create Branch: Make a new branch for your changes to keep the main branch clean.
  4. Make Changes: Edit the code as needed.
  5. Commit Changes: Save your changes with a descriptive message.
  6. Push Changes: Upload your changes to your GitHub fork.
  7. Create Pull Request: Propose your changes to the original repository.

Scientific Notations:

  • Git: A distributed version control system for tracking changes in source code.
  • Branch: A parallel version of the repository, allowing for isolated changes.
  • Commit: A record of changes made to the repository.
  • Pull Request: A request to merge changes from one branch to another.

Test Cases:

Since this script is a set of instructions rather than executable code, it is not possible to write test cases for it. The instructions guide users through a series of manual steps on GitHub and their local machines.

```markdown

Contribute to Our Open-Source Python App!

Hello, amazing developers! 🌟

We're thrilled to have you here and excited about the possibility of you contributing to our open-source Python app. Whether you're a seasoned coder or just starting out, your contributions are incredibly valuable to us. Here's how you can get involved:

How to Contribute

  1. Fork the Repository: Start by forking our repository to your GitHub account. This creates a copy where you can make changes.

  2. Clone the Repository: Clone the forked repository to your local machine using: bash git clone https://github.com/your-username/your-repo-name.git

  3. Create a Branch: Create a new branch for your feature or bug fix: bash git checkout -b feature-or-bugfix-name

  4. Make Your Changes: Implement your changes in the code. Don't forget to write tests if applicable!

  5. Commit Your Changes: Commit your changes with a meaningful commit message: bash git commit -m "Description of the changes"

  6. Push to GitHub: Push your changes to your forked repository: bash git push origin feature-or-bugfix-name

  7. Create a Pull Request: Go to the original repository on GitHub and create a pull request. Provide a clear description of your changes and why they are necessary.

Guidelines

  • Code Style: Please follow the PEP 8 style guide for Python code.
  • Documentation: Ensure your code is well-documented. If you add new features, update the documentation accordingly.
  • Testing: Run existing tests and add new ones to cover your changes.

Releasing (maintainers)

Publishing to PyPI is driven entirely by the Publish to PyPI GitHub workflow (.github/workflows/main.yml), which runs only when a GitHub release is published — creating the release is the deliberate act that ships. There is no release script. The manual steps are:

  1. Bump the version with uv (updates pyproject.toml and uv.lock): bash uv version --bump patch # or minor / major

  2. Update CHANGELOG.md — add a ## [X.Y.Z] - YYYY-MM-DD section for the new version. Keep requirements.txt in sync for non-uv users: bash uv pip compile pyproject.toml -o requirements.txt

  3. Commit and push to main (pushes alone never publish): bash git commit -am "Release version X.Y.Z" git push origin main

  4. Tag with the version number and push the tag: bash git tag vX.Y.Z git push origin vX.Y.Z

  5. Create the GitHub release from that tag — this is what triggers the workflow (tests → build → uv publish): bash gh release create vX.Y.Z --title "vX.Y.Z" --notes-from-tag (or use the GitHub web UI's Releases → Draft a new release, pasting the changelog section as the notes.)

If the workflow fails at the publish step with a "file already exists" error, the version in pyproject.toml was not bumped — PyPI never accepts the same version twice.

Need Help?

If you have any questions or need assistance, feel free to open an issue or join our community chat. We're here to help and support you every step of the way.

Thank you for considering contributing to our project. Together, we can make something truly special! 💖

Happy coding! 🚀