How to open Issues - RPI-Food-Finder/RPIFoodFinder GitHub Wiki

Contents

For those new to GitHub

For those new to GitHub or that have never opened an issue before this will be a step by step guide on how to create issues for food finder. This applies to users and devs as anyone could be new to GitHub. To start off you will need to create an account. Do that first them comeback!

  1. To begin you will need to go to the main page of the repository. Use the below picture as reference.
  1. You then need to select the issues tab. Use the below picture as reference.
  1. From there you click on new issue. Use the below picture as reference.
  1. You should see our lovely list of issue templates. If you are developer for RPI Food Finder read our issue standards here and if you are a user you can read our standards here
  1. For the sake of this guide I am going to fill out a bug report issue but you can click on what ever template pertains to your issue. Here is what it looks like once opened. (What ever template you select may look a little different but the following steps still apply)
  1. We are going to break down each section of issues. First we have the title, referenced below. The title is the name of your issue and what others see from the main issue page. You use this to generally describe the issue form you are filling out. For example I may rename this title to "[BUG] Can't see commons dining hall menu".
  1. Next we have the body of the issues. This is where you put the information pertaining to your issue. This can be one or multiple text boxes. Each one has a name, a short description of the contents, and a little example of what you can write.
  1. On the right of the body we can see some extra information pertaining to the issues. If you are a User don't worry about this step and just skip to the next one. If you are a dev you mainly need to pay attention to the assignee and labels. Assignee is who is currently assigned to an issue, so if you want to work on an issue assign yourself to it. Labels are a way for use to categorize issues in the repository. Most of them are pretty self explanatory but here is a guide anyways.
  1. Finally, after filling out all necessary information you can submit the issue by clicking the big submit new issue button at the bottom. Referenced here.
  1. Congratulations you have create a new issue! You can continue reading to see our standards for user and developer issues.

For Users

This is less of a guide on how to create issue but what we expect to see out of user made issues.

As a user you can create an issue if you want. Most likely you have a question about something and the way to get that to the dev team is via an issue. So this means the issue's you'll be creating issues under the "A Question" template. You can read more about what we expect out of these issues below.

General Rules

  • Use the correct template
  • Be as specific as possible, clarity is always appreciated
  • Try to add Screenshots or Diagrams to what you reference

A Question

This is the template mainly for users that want to ask questions that are not already under FAQ. You can ask questions about anything, new features you want to see, enhancements to existing features, how some random function works, etc. If its Food Finder related you can ask a question about it. Try to add the appropriate tags, if you don't know which ones to add don't bother a dev can do it for you.

Other Issue Templates

As a user we would rather you only ask questions but if you do want to request features and enhancements formally read the section about it under for devs. If its a bug you can try filling out the bug report form but contacting a member of the dev team would be most appropriate as they can create the issue for you with all the necessary information.

For Devs

This is less of a guide on how to create issue but what we expect to see out of dev made issues.

As a dev creating issues for problems or features being implemented is a must. We are trying to keep the repository issue based. This means every feature has an issue attached to it that way we know who is working on what. It also allows us to figure out what we want to implement next. We were originally going to use a private Trello board for this but that wouldn't be very open source friendly. Now I'll explain some general rules when it comes to creating issues and guidelines for each kind of issue.

General rules

  • Assign your self to the issues you want to work on
  • Use appropriate tags
  • Use the correct template
  • Be as specific as possible, clarity is always appreciated

Bug Reports

Bug Reports are for bugs. These can be bugs of any kind. If you are unsure if something is really a bug or not still make an issue calling it a bug. Try to provide as much detail as possible so it can be easy to spot and fix. Please add all the necessary tags, if its a feature breaking bug add the priority tag.

Enhancement Requests

Enhancement Requests are issues for existing features. So if you want to make something that already exists better this is the type of issue you would create. This includes but is not limited to minor changes in UI, navigation, integration, security, etc. Make sure you use the Enhancement label when creating the issue, it should be on by default but you never know. Use any other appropriate label as well, if unsure another dev can always add or remove them. The enhancements can be made onto dev so just pull to dev when changes are made.

Feature Requests

Feature Requests are issues for new features. So if you want to implement something that does not already exists this is the type of issue you would create. This includes but is not limited to major changes in UI, navigation, integration, security, etc. Make sure you use the Enhancement and Suggestion labels when creating the issue, they should be on by default but you never know. If accepted a new branch off dev with the feature name will be created. Add that to your codebase and pull to it when changes are made.

A Question

For the most part as a dev you will never have to open one of these issues. They are more meant for users but if you want to fill one out go ahead.