Skip to content

4.1 GitHub Issues Guide

Jump to bottom
mukunzidd edited this page Apr 23, 2024 · 1 revision

Creating rich and effective user stories as issues on GitHub is crucial for managing and tracking project requirements, tasks, and bugs. Here's a guide on how to craft well-structured user stories, focusing mainly on descriptions:

1. User Story Structure

User stories should follow the common format: "As a [user role], I want to [action/feature] so that [benefit/value]." This structure helps define the user's perspective, the desired functionality, and the motivation behind it.

Example: "As a buyer, I want to be able to add products to my shopping cart so that I can easily purchase multiple items at once."

2. Story Description

A description provides a clear and detailed description of each user story. The description should expand on the user story title and include any additional context, requirements, edge cases, acceptance criteria, or the definition of done.

Features

# User Story: Shopping Cart Management

## Description

As a buyer, vendor, or admin, I want to have a reliable and efficient shopping cart system so that customers can easily manage their purchases, vendors can track orders, and admins can monitor the overall shopping experience.

The shopping cart system should support the following operations:

- Create a new shopping cart for a user (authenticated or guest)
- Add items to the shopping cart
- Update item quantities in the shopping cart
- Remove items from the shopping cart
- Retrieve the current state of the shopping cart
- Persist the shopping cart data across user sessions

### Acceptance Criteria

- [ ] Buyers can create a new shopping cart
- [ ] Buyers can add, update, and remove items from their shopping cart
- [ ] Buyers can retrieve the current state of their shopping cart
- [ ] Shopping cart data is stored in a persistent storage (e.g., database)
- [ ] Shopping carts are associated with user sessions or authenticated users
- [ ] Concurrent cart operations are handled with thread-safety and data consistency
- [ ] Appropriate error handling and validation are implemented for cart operations

## Developer Notes

- Design and implement the data model for the shopping cart (e.g., using a database or in-memory store)
- Define the API endpoints and request/response payloads for cart operations
- Integrate with the product catalog service to fetch product details and validate item availability
- Handle edge cases such as out-of-stock items, removed products, or pricing changes
- Implement caching mechanisms for frequently accessed cart data (optional)
- Ensure scalability and performance optimizations for high-traffic scenarios
- Implement logging and monitoring for cart operations

## Related Issues

- #23 (Product Catalog Integration)
- #47 (User Authentication and Session Management)

In this example, the user story is focused on the backend implementation of the shopping cart management feature. The key aspects covered include:

  • Description: Outlines the main objectives and operations related to managing the shopping cart on the backend.

  • ** Acceptance Criteria:** Lists the specific requirements and tasks that need to be completed for the backend implementation, such as implementing API endpoints, storing cart data, handling concurrency, and error handling.

  • Developer Notes: Provides technical details and considerations for the development team, including data modeling, integration with other services, edge case handling, caching, scalability, and performance optimizations.

  • ** Related Issues:** Links to other issues or tasks that may be related or dependent on this user story, such as product catalog integration, user authentication, database schema design, and API documentation.

Chores

### Chore: Set Up Project README and Badges

#### Description

As a developer, I want to create a comprehensive README file for the e-commerce project, providing crucial information about the project, its setup, and its status. Additionally, I want to add relevant badges to the README to display important project metrics and build statuses at a glance.

A well-written README file and informative badges will help new contributors and stakeholders understand the project quickly and make it easier to collaborate and contribute effectively.

#### Tasks

- [ ] Create a README file in the root directory of the project repository
- [ ] Add a brief description of the project, its purpose, and its key features
- [ ] Include installation instructions and steps for setting up the development environment
- [ ] Document the project's technology stack, dependencies, and any external services or APIs used
- [ ] Provide instructions for running the application locally and executing tests
- [ ] Add a section for contributing guidelines, code of conduct, and issue reporting
- [ ] Set up badges for build status, test coverage, code quality, and any other relevant metrics
- [ ] Integrate the badges with the appropriate services (e.g., GitHub Actions, Codecov, CodeClimate)
- [ ] Update the README with the necessary badge markup and links

#### Developer Notes

- Follow best practices for writing clear and concise README documentation
- Use appropriate headings, formatting, and code snippets for better readability
- Consider adding screenshots, diagrams, or other visual aids to enhance the README
- Research and select relevant badges that provide valuable information about the project
- Ensure that the badge services are properly configured and integrated with the project

#### Related Issues

- #3 (Continuous Integration Setup)
- #8 (Code Quality and Linting Configuration)
- #15 (Test Coverage Reporting)

#### Definition of Done

- The README file is created in the project repository's root directory
- The README includes all necessary sections and information, following best practices
- Relevant badges (e.g., build status, test coverage, code quality) are integrated and displayed in the README
- The badges are properly configured and linked to the appropriate services
- The README provides a clear and comprehensive overview of the project for new contributors and stakeholders

In this example, the chore issue focuses on setting up the project README file and adding necessary badges to display important project metrics and build statuses. The key aspects covered include:

  • Description: Outlines the main goal and motivation behind creating a comprehensive README and adding badges.

  • Tasks: Lists the specific tasks that need to be accomplished, such as creating the README file, adding project information and setup instructions, documenting the technology stack and dependencies, providing contributing guidelines, setting up badges, and integrating with badge services.

  • Developer Notes: Provides guidance and considerations for the development team, including following best practices for README writing, using appropriate formatting and visuals, researching and selecting relevant badges, and ensuring proper configuration and integration of badge services.

  • Related Issues: Links to other issues or tasks that may be related or dependent on the README and badges, such as continuous integration setup, code quality and linting configuration, and test coverage reporting.

  • Definition of Done: Specifies the criteria that must be met for the chore to be considered complete, such as the README file being created with all necessary sections, badges being integrated and displayed, proper configuration and linking of badge services, and the README providing a clear and comprehensive overview of the project.

Bugs

  • Describe the issue or unexpected behavior.
  • Provide steps to reproduce the bug.
  • Include any relevant error messages or screenshots.
  • Mention the affected browser(s), operating system(s), or device(s).

Example:

# Bug: Incorrect Total Price Calculation in Shopping Cart

## Description

As a buyer, when I add multiple items to my shopping cart and proceed to checkout, the total price displayed on the checkout page is incorrect. It seems to be miscalculating the total price, resulting in either an over or under-charged amount.

### Steps to Reproduce

1. Open the e-commerce website
2. Browse and add at least three different products to the shopping cart
3. Proceed to the checkout page

**Expected Behavior:**
The total price displayed on the checkout page should be the sum of the prices of all items in the cart, including any applicable taxes or fees.

**Actual Behavior:**
The total price displayed on the checkout page is incorrect. For example, if the sum of the three items in the cart is $100, the total price shown might be $90 or $110.

### Additional Information

- **Browser**: Google Chrome (Version 91.0.4472.114)
- **Operating System**: Windows 10 (Version 20H2)
- **Reproducibility**: This issue can be consistently reproduced.
- **Severity**: High (Incorrect pricing could lead to financial losses or customer dissatisfaction)

## Potential Causes

- Incorrect calculation logic in the shopping cart total price computation
- Inconsistent data formats or units (e.g., currency, decimal places) between the product catalog and shopping cart
- Missed edge cases or special scenarios (e.g., discounts, promotions, taxes, shipping fees)

## Suggested Steps

- Review the shopping cart total price calculation logic and identify potential issues
- Check for data consistency between the product catalog and shopping cart data structures
- Ensure that all relevant factors (discounts, taxes, fees) are correctly accounted for in the total price calculation
- Add unit tests to cover various scenarios and edge cases for total price calculation

## Related Issues

- #27 (Tax and Shipping Fee Calculation)
- #34 (Discount and Promotion Management)

## Attachments

- [screenshot_incorrect_total.png](screenshot_incorrect_total.png) (Screenshot showing the incorrect total price on the checkout page)

In this example, the bug issue describes an incorrect total price calculation in the shopping cart. The key aspects covered include:

  • Description: Outlines the issue and the unexpected behavior observed by the user (buyer).

  • Steps to Reproduce: Provides a clear set of steps to reproduce the bug, allowing developers to easily recreate and investigate the issue.

  • Expected Behavior and Actual Behavior: Contrasts the expected correct behavior with the actual incorrect behavior observed.

  • Additional Information: Includes relevant details such as the browser, operating system, reproducibility, and severity of the bug.

  • Potential Causes: Lists possible causes or factors that might be contributing to the bug, such as incorrect calculation logic, data inconsistencies, or missed edge cases.

  • Suggested Steps: Provides recommendations or suggestions for developers to investigate and resolve the bug, such as reviewing the calculation logic, checking data consistency, accounting for all relevant factors, and adding unit tests.

  • Related Issues: Links to other issues or tasks that may be related to or impacted by this bug, such as tax and shipping fee calculation or discount and promotion management.

  • Attachments: Includes a screenshot or other visual aids to better illustrate and document the bug.

Clone this wiki locally