Issues and features#

Overview#

Before starting on a bug fix or developing a new feature for Thevenin, please follow the steps outlined below to ensure efficient collaboration and alignment with the project’s goals. Whether you’re reporting a bug, suggesting a feature, or volunteering to work on an issue, these guidelines will help maintain smooth development and communication.

Steps to report an issue#

  1. Check for existing issues

  • Always check the issues page on GitHub before starting any new work.

  • If a bug report or new feature request already exists, review the comments and status to see if someone is already working on it.

  • If you are interested in working on the issue, leave a comment requesting the issue be assigned to you. Feel free to express your interest or add any additional context if you are experiencing the same bug or would benefit from the new feature.

  1. Report a new issue

  • If no issue exists for the bug or feature, open a new issue. Be detailed in your description, providing steps to reproduce the bug or a clear rationale for the feature.

  • If you’d like to take on the issue yourself, indicate this in the issue and request that it be assigned to you.

  • Before proceeding with any major work, wait for a maintainer’s response to ensure the issue aligns with the project’s scope and future plans.

Best practices#

When filing an issue, follow these best practices to help the maintainers understand the problem or feature request efficiently:

  • For bugs: - Use the “Bug Report” template. - Clearly describe the problem and how to reproduce it. - Specify the environment (operating system, Python version, etc.) where the bug occurred. - Include a minimal reproducible example, relevant logs, error messages, etc.

  • For features: - Use the “Feature Request” template. - Explain the problem the feature will solve, and why it’s important. - Suggest how the feature should work and provide any references or examples if needed.

Working on an issue#

Once your issue is approved and assigned, follow the GitHub flow branching strategy for development:

  1. Fork the repo: If you haven’t already, create a fork of the repository.

  2. Create a Branch: Start by creating a new branch from the main branch. Name your branch with a short description of the bug or feature. Consider including the issue number in the name as well.

  3. Work in Manageable Chunks: Ensure your pull request is manageable for reviewers. If your changes involve many files or a large number of lines, consider splitting the work into smaller, logical pull requests. This makes it easier for maintainers to review and approve your changes.

  4. Submit a Pull Request: Once your work is complete, submit a pull request (PR) to the main branch. Reference the corresponding issue in your PR description to keep everything linked and easily trackable.

For a more detailed breakdown of these steps you will likely want to read through version control.

The development team welcomes contributions! However, to keep the project maintainable and focused, it’s important that every change or new feature starts with an issue. This allows maintainers to review, prioritize, and ensure the work aligns with the project’s vision.

Remember:

  • Engage early: Always seek feedback from maintainers before diving too deep into development, especially for larger changes or features.

  • Be considerate: Ensure your changes are well-organized, documented, and easy to review. This will help expedite the review and approval process.

Getting help#

If you’re unsure whether your contribution fits within the scope of the project or if you need help getting started, feel free to ask questions by commenting on issues or reaching out to the maintainers. Collaboration is key to the success of Thevenin, and we’re here to support you.

On this page