Issue Creation

How to correctly create an issue in the Practicum repositories.

Issues are the starting point for all work in the Practicum. Although many steps are automated through our GitHub bot and project settings, it is still important to follow the correct naming and setup process when creating a new issue.

---

🎯 Purpose of This Step

During Sprint Planning, students claim tasks and then create issues for the work they will complete.
Issues act as the source of truth for:

• What you are building
• Why you are building it
• How it will be reviewed
• Which sprint it belongs to

Even with automation, issues must be created consistently so the team can track progress effectively.

---

⚙️ What’s Automated (No Action Needed)

Our GitHub bot automatically performs the following actions:

✔️ Adds your new issue to the correct GitHub Project

No need to manually assign the issue to the Project board.

✔️ Identifies the project’s current two-week sprint cycle

Sprints for each project are configured to auto-generate.

✔️ Applies default metadata (per repository settings)

Additional automation—such as summaries or auto-labeling—may be added in future updates.

---

🧑‍💻 What You Still Need To Do

1. Use the Correct Naming Convention

Use the following format for titles:

• feature: <Title of Issue>

• bug: <Title of Issue>

• refactor: <Title of Issue>

• experiment: <Title of Issue>

• documentation: <Title of Issue>

• chore: <Title of Issue>

Examples:

• feature: Add user registration form
• bug: Fix footer alignment on mobile
• refactor: Simplify middleware structure
• documentation: Add setup steps to README

Keep titles short, descriptive, and professional.

---

2. Add the Issue to the Current Sprint

Although sprints auto-generate every two weeks, you must still manually attach your issue to the most recent sprint.

To do this:

1. Create your issue.
2. On the right-hand sidebar under Projects → Sprint, select the latest sprint cycle.
3. Confirm that the sprint is applied correctly.

Note: Sprint naming conventions and durations may change based on ongoing adjustments to the program. Always choose the most recent sprint in the dropdown.

---

3. Write a Clear Issue Description

Your issue description should include the following sections:

Problem / Goal

Explain what you're building or fixing.

4. Assign the Issue to Yourself

This ensures proper tracking during the sprint and helps your PM/TA understand task ownership.

---

💡 Best Practices

• Keep issue titles short and readable.
• Write acceptance criteria for every issue.
• If unsure about the type, choose feature or ask for clarification.
• Create your issue before creating a branch.
• Use labels sparingly unless the repo requires them.

---

⚠️ Common Mistakes to Avoid

Mistake	Why It's a Problem
Forgetting to add the issue to the current sprint	Issue won’t appear during sprint tracking
Vague descriptions	Makes implementation unclear
Creating issues after code is written	Breaks the expected workflow
Combining multiple tasks into one issue	Leads to large, messy PRs

---

🔗 Next Step

➡️ Proceed to: Branch Creation