Raising issues

Raising issues is an essential part of contributing to an open source project. Before you start, it’s recommended that you have a basic understanding of Markdown and GitHub, which are commonly used in this workflow. Markdown is a lightweight markup language that is used to format and style text on the web. You can find a comprehensive guide to Markdown on the GitHub website

If you’re not familiar with GitHub, it’s a web-based platform that provides tools for version control, code management, and collaboration. GitHub provides a step-by-step guide to getting started with their platform on their website

It’s important to check whether your idea or issue has already been raised by someone else. You can do this by searching through the project’s existing issues on GitHub. If you find an issue that is similar to yours, please comment on it to let others know that you’re also interested in working on it.

If the issue has already been closed, or if it only partially solves your problem, it’s recommended that you open a new issue with a reference to the old one. This can help to keep the discussion organized and ensure that all relevant information is easily accessible.

Remember, raising an issue is an opportunity to improve the project and contribute to the open source community. With a little bit of effort and attention to detail, you can help make a real difference

Issue templates

We have issue templates for different types of issues. Please use the appropriate template for your issue. If you’re not sure which template to use, please use the General template.

  • General template (preview) : This is the default template for raising an issue. Use this template if you’re not sure which template to use.
  • Bug report template (preview) : Use this template to report a bug or problem with the project.
  • New feature Request template (preview) : Use this template to request permission to add a new course to the list.

Writing a clear title and description

When opening an issue, it’s important to write a clear and concise title that accurately reflects the problem or suggestion you want to raise. The title should be descriptive enough so that others can quickly understand the issue, but not too long or complicated.

In the issue description, provide as much detail as possible about the issue or suggestion. Include steps to reproduce the problem if applicable, and any relevant information or context that can help others understand the issue better.

Using Issue labels

Issue labels are used to categorize and organize issues in an open source project. They can help contributors quickly identify the type and status of an issue, and can also help maintainers prioritize and manage the project’s backlog of issues.

When raising an issue, make sure to choose the appropriate label(s) that best describes the issue. For example, if you’re reporting a bug, you might use the “bug” label. If you’re suggesting a new feature or improvement, you might use the “enhancement” label.

Some common issue labels you might see in a GitHub project include:

  • Bug: Used to report an error or problem with the code or functionality of the project.
  • Enhancement: Used to suggest a new feature or improvement to the project.
  • Documentation: Used to suggest changes or improvements to the project’s documentation.
  • Help wanted: Used to indicate that the project maintainers are actively seeking contributions to help resolve the issue.
  • Good first issue: Used to indicate that the issue is suitable for new contributors who are just getting started with the project.

Contributing to issue discussions

If you’re interested in working on an issue, please leave a comment to let others know. This will help to avoid duplicate work and ensure that the issue is assigned to the right person. Once you’ve opened an issue or commented on an existing one, it’s important to actively participate in the discussion. This means responding to comments and questions from others, providing additional information or clarification if needed, and being open to feedback and suggestions.

Conclusion

Raising issues is an important part of contributing to open source projects. By following these guidelines, you can help ensure that your issue is clear, well-documented, and easy for others to understand. Remember to actively participate in discussions, follow up on issues, and contribute code if you’re able to. With a little effort and collaboration, we can all help make open source projects better for everyone.