Introduction

Contributing to open source projects on GitHub can seem intimidating at first. One of the easiest and most impactful ways to contribute is by creating well-structured issues. Whether you’ve found a bug, need clarification on a feature, or have a suggestion for improvement, a well-written GitHub issue can be the first step toward a successful contribution.

In this guide, I'll walk you through how to create issues that will grab attention, get feedback faster, and set you apart in the open-source community. Plus, I'll show you how to use some Markdown tricks to make your issues stand out!

Why Are Issues Important?

An issue is essentially a conversation starter. Whether you're reporting bugs, suggesting features, or asking for guidance, issues help maintainers manage the project.

Here’s how creating great issues can make a difference:

• Clarity: Maintainers and contributors can quickly understand the problem.
• Actionability: It becomes easier to address the issue with steps provided.
• Professionalism: A well-written issue shows you respect the project and its maintainers.

Now, let’s dive into how to write one!

1. Use a Clear and Descriptive Title

The first thing maintainers and contributors will see is the title of your issue. You want to grab their attention with a clear, concise title that explains what the issue is about.

Example of a Bad Title:

Error with app

Example of a Good Title:

Bug: App crashes when selecting a file larger than 5MB

The second title is much clearer and gives maintainers an idea of what the problem is even before reading the details.

2. Provide Detailed Descriptions

In the body of the issue, explain the problem in detail. Here's what to include:

• What happened? Describe the issue.
• What were you expecting? Mention what you expected to happen.
• Steps to Reproduce: Provide a clear and reproducible step-by-step guide to recreate the issue.
• Environment Information: Mention relevant versions like browser, OS, or application version.

Example:

### Description
The application crashes when I attempt to upload a file larger than 5MB.

### Expected behavior
The app should handle large files by either compressing them or showing an error message, rather than crashing.

### Steps to Reproduce
1. Open the app.
2. Click on 'Upload File'.
3. Choose a file larger than 5MB.
4. Observe the app crashing.

### Environment
- OS: Windows 10
- App Version: v2.3.4
- Browser: Chrome 96.0

3. Use Markdown to Enhance Your Issue

Markdown is a lightweight markup language that GitHub supports to format text. Learning a few simple Markdown tricks can help make your issue more readable and engaging.

Bold & Italics

Use bold or italics to highlight important points:

**Bold** text
*Italic* text

Code Blocks & Inline Code

If you're referencing code, make it easy to read by using inline code or code blocks:

• Inline code: Surround short snippets with single backticks (`).
• Code blocks: Surround longer code samples with triple backticks (```).

`
Here's a sample of the code:
`
def upload_file(file):
if file.size > 5 * 1024 * 1024: # 5MB limit
raise ValueError("File too large!")
`

Headers

Use headers to organize your issue into sections, which makes it easier for others to follow.

`

H1 for main titles

H2 for sub-sections

H3 for smaller subsections

`

Bullet Points & Numbered Lists

For listing steps or multiple items, use bullet points or numbered lists.

`

• First item
• Second item
  • Sub-item

1. First step
2. Second step `

Tables

You can even include tables to make things more structured, especially useful when comparing versions, features, or errors.


| Feature | Status |
|--------------|---------|
| Upload | Working |
| Compression | Buggy |
| Notifications| Missing |


This will render as:

One hack to avoid stretching your columns is to align them either to the right or to the left using the : as show on this github doc:


| Left-aligned | Center-aligned | Right-aligned |
| :--- | :---: | ---: |
| git status | git status | git status |
| git diff | git diff | git diff |


This will render as:

4. Attach Screenshots or GIFs

Sometimes, a picture is worth a thousand words. If you’re reporting a visual bug or an error message, consider attaching screenshots or a screen recording.


![App crashing when uploading large file](https://link-to-screenshot.png)


If the issue is hard to reproduce, you can also

record a short GIF showing the problem in action. Tools like LICEcap or Kap can help create simple screen recordings, which can then be uploaded directly to GitHub issues.

5. Suggest Possible Solutions (Optional)

While this is optional, maintainers appreciate when contributors suggest potential fixes. Even if you’re not sure how to fix the issue, offering ideas can lead to productive discussions.

Example:

`

Possible Solution

The app could either:

1. Show an error message when files exceed the size limit.
2. Automatically compress files before uploading. `

This not only shows that you’re thinking critically about the issue but also saves maintainers some time by pointing them in the right direction.

6. Be Polite and Appreciative

Open source maintainers often work on projects in their free time, so being polite and respectful in your issue goes a long way. Thank them for their work and avoid demanding tone.

Example:


Thanks for all the hard work on this project! I'm looking forward to hearing your thoughts on this issue.


7. Use Labels Appropriately (If You Have Permissions)

Some repositories allow contributors to add labels to their issues. If you have permission, use labels wisely to categorize your issue as a bug, feature request, or question. This helps maintainers triage issues faster.

Common Labels:

• bug
• enhancement
• question
• documentation

Example:


Labels:bug,high-priority


Example of a Complete Issue

Here’s how a polished, well-organized issue might look:

`

Bug: App crashes when selecting a file larger than 5MB

Description

The application crashes when I attempt to upload a file larger than 5MB.

Expected behavior

The app should handle large files by either compressing them or showing an error message, rather than crashing.

Steps to Reproduce

1. Open the app.
2. Click on 'Upload File'.
3. Choose a file larger than 5MB.
4. Observe the app crashing.

Environment

• OS: Windows 10
• App Version: v2.3.4
• Browser: Chrome 96.0

Possible Solution

The app could either:

1. Show an error message when files exceed the size limit.
2. Automatically compress files before uploading.

Screenshots

`

Conclusion

Writing a great GitHub issue doesn’t require advanced skills, just attention to detail, clarity, and respect for the maintainers’ time. Following these tips will not only increase the chances of your issue getting addressed quickly but will also help you stand out as a thoughtful and professional contributor.

Happy contributing!

P.S. If you’re new to Markdown, GitHub has a handy Markdown Guide that you can check out to level up your formatting skills!

This post is also part of my effort to encourage newbies to actively contribute to open-source projects. If you have any questions or need guidance, feel free to leave a comment!

If you found it helpful or have any further questions, feel free to reach out to me. I’m always happy to chat about open source, coding, or just technology in general.

You can connect with me on:

LinkedIn – Let’s network and exchange ideas.
GitHub – Check out my projects or collaborate on open-source.
Twitter – Follow me for tech updates, discussions, and more!

Please feel free to drop a message or follow me on any platform. I’m always looking forward to meeting new people in the tech community!