# How to Report Issues with AI-For-Beginners: A Complete Guide to GitHub Issues

> Learn how to report issues with AI-For-Beginners on GitHub. Follow our guide to effectively open GitHub issues with clear descriptions and steps for faster resolution.

- Repository: [Microsoft/AI-For-Beginners](https://github.com/microsoft/AI-For-Beginners)
- Tags: how-to-guide
- Published: 2026-08-24

---

**Open a GitHub Issue with a clear description, reproduction steps, and environment details after searching existing issues first.**

The AI-For-Beginners repository by Microsoft is an open-source curriculum designed to introduce learners to artificial intelligence. When you encounter typos, broken links, or technical problems, reporting them through GitHub Issues helps maintainers track and resolve problems efficiently. This guide walks through the exact workflow specified in the project's troubleshooting documentation.

## Search Existing Issues Before Reporting

Always check if your problem has already been reported. Duplicate issues create unnecessary overhead for maintainers and fragment discussion.

Navigate to the [GitHub Issues list](https://github.com/microsoft/AI-For-Beginners/issues) and use the search bar to filter by keywords. Look for closed issues as well—your problem may have been resolved in a recent update.

If you find a matching issue, add a comment with any new details rather than opening a duplicate.

## Open a New GitHub Issue with Required Details

When no existing issue matches your problem, create a new one by clicking **"New issue"** on the issues page. The repository provides a template that guides you through the required fields, as documented in [[`troubleshoot.md`](https://github.com/microsoft/AI-For-Beginners/blob/main/troubleshoot.md)](https://github.com/microsoft/AI-For-Beginners/blob/main/troubleshoot.md#L258-L267).

Include these elements in your issue:

- **Specific location** – The exact file path (e.g., [`lessons/5-NLP/18-Transformers/README.md`](https://github.com/microsoft/AI-For-Beginners/blob/main/lessons/5-NLP/18-Transformers/README.md))
- **Problem description** – A concise explanation of the symptom
- **Reproduction steps** – Numbered steps that reliably trigger the error
- **Environment details** – Operating system, Python version, and Conda environment name
- **Supporting evidence** – Screenshots or log excerpts when applicable

### Example Issue for a Broken Link

```markdown
**Title:** Broken link in the Perceptron lesson notebook

**Description:**
The link to the Perceptron notebook in `lessons/3-NeuralNetworks/03-Perceptron/README.md`
points to a non-existent file (`Perceptron.ipynb`). Clicking the link results in a 404 error.

**Steps to reproduce:**
1. Open the README file in the Perceptron lesson.
2. Click the link labeled "Notebook".
3. Observe the 404 error page.

**Environment:**
- OS: macOS 14.0
- Python: 3.11.4 (conda env `ai4beg`)

**Expected behavior:**
The link should open `Perceptron.ipynb` located in the same directory.

**Screenshots:**
*(attach a screenshot of the 404 page)*

```

## Sign the Contributor License Agreement

All contributions to the AI-For-Beginners repository require signing Microsoft's **Contributor License Agreement (CLA)**. As specified in [[`CONTRIBUTING.md`](https://github.com/microsoft/AI-For-Beginners/blob/main/CONTRIBUTING.md)](https://github.com/microsoft/AI-For-Beginners/blob/main/CONTRIBUTING.md#L5-L10), a CLA-bot automatically detects when a contributor hasn't signed and posts instructions on your issue.

The signing process is handled entirely through the bot's comments—no separate paperwork is required.

## Follow Up and Collaborate on Resolution

After submitting your issue:

1. **Monitor notifications** – Maintainers may request additional information or clarification
2. **Respond promptly** – Quick replies keep the resolution process moving
3. **Submit a fix if possible** – If you can resolve the problem yourself, reference the issue number in your pull request description (e.g., "Fixes #123")

The "Help Wanted" call-out in [[`README.md`](https://github.com/microsoft/AI-For-Beginners/blob/main/README.md)](https://github.com/microsoft/AI-For-Beginners/blob/main/README.md#L63-L66) explicitly invites community participation in improving the curriculum.

## Close the Loop After Resolution

Once a fix is merged, the associated issue typically closes automatically. You can still comment on closed issues for follow-up questions, or open a new discussion if unrelated problems arise.

## Summary

- **Search first** – Check existing issues to avoid duplicates
- **Use the template** – Follow the structure in [`troubleshoot.md`](https://github.com/microsoft/AI-For-Beginners/blob/main/troubleshoot.md) for complete reports
- **Be specific** – Include exact file paths, reproduction steps, and environment details
- **Sign the CLA** – Required before any contribution is accepted
- **Stay engaged** – Respond to maintainer questions and consider submitting a fix yourself

## Frequently Asked Questions

### What types of problems should I report through GitHub Issues?

Report any defect that affects the learning experience: typos in documentation, broken links, code errors in notebooks, outdated dependencies, or unclear explanations. The AI-For-Beginners maintainers track all curriculum improvements through the GitHub Issues system.

### Do I need a Microsoft account to report issues?

No—any GitHub account can open issues. However, you must sign the Microsoft CLA before your contributions (including detailed bug reports that lead to pull requests) are fully processed. The CLA-bot guides you through this automatically.

### How long does it typically take for issues to be resolved?

Resolution time varies based on issue complexity and maintainer availability. Simple typos may be fixed within days, while curriculum-wide updates take longer. The project is community-driven with Microsoft sponsorship, so active contributors often help accelerate fixes.