Home - VasilyF/rocks GitHub Wiki

This document briefly describes the aspects of github that are used for this project and where to look to find what you need.

Issues

Issues (also called tickets) are tasks pertaining to the project. Issues may involve changing things in the source code such as coding in a new feature or fixing a bug, or they be centered around research and documentation and not involve any changes to the source code.

Who can create issues?

Anyone is free to contribute new issues to request new features and bug fixes.

How do I go about creating an issue?

Using Issues > New issue , for reporting a bug please use the provided issue template. Otherwise, feature requests and other issues can me made as a blank issue. Include as much metadata as possible regarding the ticket, this includes: any relevant labels, the repository project (Rocks Issues/Pull Requests) and the current milestone.

What are labels?

Labels are there purely for organization and filtering of issue based on the kind of task, the following are some common labels used within the project:

  • documentation - task involves adding documentation, this may either involve changing markdown files in the source (ie. README.md) but more often will involve adding to the wiki.
  • spike - task involves investigating a concept in order to get a better understanding of the direction in which to take the project, the results of this investigation should be documented in the wiki.
  • batch - an issue containing several small tasks that are trivial enough to incorporate all in one go. A batch should contain ~5 small issues inside it prior to being incorporated as a pull request.
  • bug - task highlights an issue that presently exists in the site
  • enhancement - task describes a proposed new feature to add to the site
  • good first issue - a task that is not too complex that will allow newbies to acquaint themselves with the application.

What is a Milestone?

Milestones correspond to versions of the app, they encompass deliverables pertaining to the currently developed version of the application. There should be a single most recent milestone that you should include with every new issue. Essentially, it is for keeing track of what version past issues were part of. A description of the general goals for a particular version/milestone can be found in Issues > Milestones.

Projects

What github (confusingly) refers to as a project is essentially a board where you can see the status of the current and completed issues. There is one project that shows both issues and pull requests called Rocks Issues/Pull Requests, whenever you create a new issue you should add this project and mark it as TO DO. The stages on this project board are:

  • TO DO - issues that have been created but are not currently being worked on. Also, pull requests that have just been opened
  • IN PROGRESS - issues that are currently being worked on and pull requests that are currently being reviewed.
  • IN REVIEW - issues that have been PR'ed and are awaiting approval, pull requests that have been approved and that are awaiting being merged.
  • DONE - issues that have been completed (code merged into dev) and PRs that have been closed.

Note: it is admittedly clumsy to use the boards to track both issues and PRs, their main use is to track issues and it may change in the future to no longer show PRs.

Wiki

Includes documents (such as this document) that are appendages to the project itself. It may include documentation of project APIs, spike results, how-to resources, or documents that help outline the architecture of the project.

Finding what you need

The following are some resources containing important information and are part of the source files (in the root directory):

  • README - project overview and instructions for installing dependencies and running the app.
  • LICENSE - license declaration for the project.

The following files are (or will soon be) in the Wiki:

  • Home - overview of github features used.

  • Git Workflow - tutorial of the git workflow involved in starting work on a new issue and contributing the changes back to the code base.