• Identify best practices for posting issues

When you work and/or play in the world of open source software, you are part of a community that helps others maintain and improve their projects. Not only does this help others, it helps you keep growing your skills and building your experience. A common way of submitting feedback on projects, including Flatiron curriculum, is through submitting issues at the project's repository. Here we'll run through some tips to keep in mind when posting issues on others' projects.

Most often when you post an issue to a project, you'll be following the workflow for GitHub issues. In this lesson, we're not concerned with the technical details of how to post an issue, but how to define and describe your issue so that it will be clear to the project maintainer what the problem is and how to solve it.

Here are some things to consider before you post an issue:

• Share all details about the problem you've encountered and what steps you've already taken. Post relevant code, examples of the output you saw, references to documentation or other issues you uncovered in your own research. Often, the more information you can provide, the better chance the project maintainer will have in solving the issue.

• Be specific and focused with your issue. Along the same lines as the previous guideline, a statement such as "This doesn't work for me" unfortunately does not help the project maintainer understand exactly what the problem is. While you want to make sure that you're giving the full picture, also make sure that the details you're providing are to the point.

• Be polite and keep perspective. It's often a lot of work to maintain an open-source project! Respect the project maintainer's time and effort. Avoid making demands or disparaging remarks. You'll make a better impact in the community if you approach posting issues as a way you can help the project improve rather than a fix you are entitled to.

• Leverage the Issues Tab of GitHub. Often Google searches will point you back to CLOSED status issues that might ask your same question. Be sure and appreciate the debugging technique applied so that when you see the solution post you can understand where you might need to make tweaks. If someone fixes the same error message by doing something with a library like foolib-3.5.4, and on your system, you have foolib-3.5.5, you're going to be expected to have made that "tweak" yourself.

• Don't Comment on Closed Issues. When you see a closed issue, realize that while the error message might be the same, in the maintainers' minds this is a new issue. If it is a duplicate, let the maintainers decide that. As a professional courtesy, we recommend opening up a new issue and adding in the body: "This might be a repeat of issue #13 (URL)." Then you demonstrate that you know not to comment on old issues and you did your research. By showing this respect the maintainers and community will know you to be an appreciative, thoughtful, community member.

Out in the open-source community, you will sometimes run into code that could be improved. By posting issues that are thoughtful, targeted and polite, you will not only contribute to the code improvement but strengthen your own skills and community connections.

• Flatiron Help: Raising an Issue with a Lab or Lesson