GitHub is an online platform for hosting projects that use the Git revision control system to manage code. Its lightweight issue tracker helps to maintain lists of issues identi ed during the development process, including bugs, features, or other software artifacts. Although issue tracking software has been practically used in software industry, studies on using it to manage requirements remain insu cient. This paper tackles the issue by presenting a semi-formal guideline for managing requirements in agile software development projects using GitHub. The guideline is evaluated on a theoretical level by analyzing how well it guides to manage requirements and ts in an agile software development setting. It is compared against lean principles. In addition, the guideline is put into use in a case study. The studies indicate that the guideline and GitHub are well-suited for requirements management in an agile environment.
GitHub [
Lean ideology derives from Japanese car manufacturing from the middle of
1950s. In the beginning of the 21st century \being lean" has received a lot of hype
in the software engineering eld after Poppendiecks' [
The rest of this paper is organized as follows. Next section gives an introduction to GitHub. Section 3 addresses common RM practices in agile projects. Section 4 describes the guideline and its usage. In Section 5 the guideline is evaluated. The last section concludes the work. 2
The central concept in GitHub is a repository. GitHub's key aspect is its version control mechanism, so it is natural that other components are built upon this feature. The bulk of a repository's main page consists of the les and folders inside the version control system. There are navigation links to the subcomponents of the repository, and free-text search function to search multitude of things inside GitHub's repositories.
In GitHub all issues are created and tracked in an integrated issue tracker. An issue is a very vague concept; basically it is a task. However, issues can range from memos to requirements. In this study, the term issue is used as a higher level concept, and includes both requirements and tasks. A task is a concrete item that must be done in order to ful ll de ned requirements. Requirements hold, in prede ned format, the goals, business objectives and user requirements for the software. They are more abstract than tasks. Both can be divided to main and sublevel. Sublevels are to be used when a requirement or task is so large, that it is semantically wise to divide it to subcomponents. For example a task can have di erent subtasks for designing UI, creating it, designing architecture and implementation.
As shown in Figure 1, the issue tracker is composed of three components shown in three areas. The top of the screenshot is the issue tracker's inner navigation. Provided options are the default view, milestone view, labels, lters and a link to create a new issue. Below this area are exclusive general lters. In the bottom are the issues. Name, assigned labels, identi cation number, creator and elapsed time from the creation are displayed. Every issue has a checkbox, for carrying out actions like assigning a label without a need to open the issue.
The issue tracker provides a separate view for creating a new issue. User must give a name and a description of the new issue, but he can also assign a developer, desired milestone and labels. Labels are small tags that can be assigned to issues. Every label acts as a lter to the issues. Milestones are iterations and as such issues can be linked to them. An issue can always belong to a maximum of one milestone. User can observe and manage the milestones. User can toggle open and closed milestones and also milestones with or without any issues assigned to him. Every milestone can be edited, closed or deleted. Milestone's name, description and due date are also presented.
Filters refer to di erent ltering options available in the issue tracker. These lters can be divided to four categories: personal, milestone, label and state. Personal lters (\Assignee" and \Author" selections) are used to lter issues that are related with the current user. Milestone lter is for ltering issues associated to a speci c milestone. The label lter limits the issues to those that have all the selected labels assigned to them. The state lter is for ltering open and closed issues. There is also a search box that provides a way to make more elaborated lter queries using a special syntax.
When an existing issue is opened, a detailed info view is displayed. All data in the view is editable. The state is noti ed below the name of the issue. Other relevant information includes subscription to the issue and participants of the issues. Subscribing to the issue means getting noti cations about changes to the issue. The person creating the issue is automatically subscribed. Comments and references to the issue are visible below the description in a chronological order.
The last subcomponent of the repository is a wiki. Each repository has an own wiki collection that acts like any ordinary wiki instance. It consists of one or more pages that are created using one markup from the list of possibilities. 3
Paetsch and others [
Stakeholder involvement forms one of the core principles in agile methods,
and a key factor for project success [
Replacing heavyweight documentation with a lightweight alternative forms
another common practice. Documentation should not be neglected because it is
used for knowledge transfer, but it should be toned down to the minimum feasible
level due to its cost ine ectiveness [
As many agile methods take advantage of iterative software development
process, the same practice is applied in RM [
To summarize aforementioned three factors, the key aspect for agile
requirements engineering is to manage the requirements to implement the most
important ones rst in order to produce the best possible business value for the
customer [
As with agile methods in general, it should be remembered that agile
requirements engineering does not guarantee success, although correctly used can
greatly enhance chances for it. Cao and Ramesh [
Tasks and requirements can be split to smaller parts. Smaller issues give a more transparent view into what is really wanted. The bigger the issue more likely it contains too wide a topic to fully grasp. This is why we recommend to use the subtasks and sub-requirements. For example the case study contained a requirement R2.2 \There are a total of 10-15 puzzles". A natural way of splitting R2.2 to tasks was to make a task for each puzzle. The tasks could be further split to subtasks representing implementing business logic, the UI and so on.
Splitting could be done endlessly so there must be a limit to how deep the hierarchy can go. For the guideline the maximum depth is four issues: a requirement, a sub-requirement, a task and a subtask. To revise the example, an alternative to creating just one subtask for a business logic would be to create multiple subtasks to depict individual components of the business logic. These subtasks would be direct descendants of the main task.
Subtasks have some drawbacks. Too small tasks cause more work with their creation and maintainability and o er minimal bene ts. If developers are experienced, forcing them to create the subtasks might be a waste of time. On the other hand, in some cases it can help a developer further recognize the problem and its di erent areas. A good thing with subtasks is that the components they a ect are easier to identify and trace. A big task could be clogged up with a long description and dozens of comments hindering the process of nding the relevant information.
There are bene ts of not using the subtasks. When an issue is referenced, the reference shown in a comment area has the information of how many of issue's task list items are completed. With the subtasks such information cannot be displayed due to the lack of automated hierarchy handling. The second bene t is negating the overhead caused by creating and maintaining the subtasks.
Overall it is impossible to say when the bene ts of the subtasks overcome the slight waste caused by their upkeep. The decision about their use should be made case by case. The main point is that all the necessary information is present, logically structured and ndable with minor e ort. It should be noted that to get the best out of the issues, the whole team must be committed to use them. In some cases developers may nd subtasks to be just a nuisance and therefore the attitude towards the guideline might decrease causing a negligent usage. Overall it is hard to say when bene ts from de ning the subtasks overcome the slight waste caused by their upkeep. The decision about their use should be made case by case, although when information is separated to logical components, it is easier to nd and interpret. The guideline emphasizes that the necessary information must be present, logically structured and ndable with minor e ort.
Issues should always follow a strictly speci ed hierarchy where the main level issues (requirements and tasks) must exist and the subissues (subtasks and -requirements) inherit from them. Every issue should always have only one parent, but the amount of children is not limited. Figure 2 depicts this hierarchy structure. To create this structure in GitHub issue references, labels and naming conventions are to be used. Creating issues should be an activity for the whole team. Requirements and sub-requirements may be composed with only a speci ed group of team members and customer representatives, but creating tasks should involve the whole team. This has many bene ts. Seasoned developers may already have suitable solutions or have such experience which is useful in some other way. Letting the developers contribute enhances the team spirit and takes them inside the decision making process. In the best scenario, the overview of the domain and its business objectives is broadened within the team, thus building a stronger foundation for making better decisions.
As the guideline is directed towards agile environments, issues can be created iteratively. The best approach is dictated by the size of the project and its application domain. As the requirements evolve, so do the issues: new ones are created, old ones closed, modi ed or rejected, tasks are started and completed.
The creation process consists of seven steps. The rst step is deciding the title of an issue. The title should include some kind of a reference pre x that is di erent for requirements and tasks to help identifying the issue and its place in the issue hierarchy.
The second step involves writing the description of the issue. This is a very crucial step and concerns the question of how long should the description be? If too much information is given, the issue becomes cumbersome and it might be hard to nd the core information. Too vague descriptions tend to cause guessing, misleading or a need to consult somebody with better knowledge thus wasting time. If the project team is highly experienced and pro cient with the domain of the project, it might be a good idea to leave room for an individual thinking and implementation. This endorses the team and acts towards agilism which expects that experienced developers reach the best outcome without handholding.
The requirements on the other hand should be as unambiguous as possible to make sure that every stakeholder understands them the same way. The bottom line is that the issue should always have a description which is tangible. The guideline suggests that as much of the task speci c information as possible should be directly in the description.
A large amount of pictures, documents or other relatively static material should be archived somewhere else to reduce the overhead of information. For requirements it might be a good practice to document them to the wiki. In such case a short description and a link are su cient for a requirement issue.
The format of the issue's description is not prede ned, but the guideline
highly recommends that a logical structure is used throughout each issue taking
advantage of GitHub Flavored Markdown (GFM). GFM is a special hypertext
formatting syntax utilized by GitHub. It inherits from the Markdown [
The description shall comprise four parts: summary, information, task list and references. The summary explains the issue in few sentences. The information part consists of all the relevant information. If this data is stored somewhere else, links should be used to point out the source. The task list is utilized when a task involves steps, that are not split to own tasks yet need to be monitored. They should also be used as subtask replacements if the subtasks are not used.
Otherwise the format of the description should be kept as simple as possible. Developers should be aware of GFM's special features that are not included in the basic Markdown. For example @-notation or \mentioning" can be used to notify a speci c person or a team about the issue. Mentioning creates a lter into the issue tracker for the ones mentioned.
Because GitHub itself does not recognize any kind of hierarchical constraints between issues, such a behavior must be implemented manually. The way the guideline achieves this is by using labels, naming conventions for issues and issue references. An existing issue can be referenced from another issue establishing a link between them. In GitHub referencing an issue from another means that within the rst issue's view, there is a hyperlink pointing to the second issue. The link is accompanied by a comment. The issue referenced must exist to get the linking to work. This can cause inconvenience when a main task is created before its subtasks. The guideline recommends that the references are updated when new issues are created. Referencing issues follows the same rules as the hierarchy of them. The exception is that if an issue has a close relation with another issue which is not a descendant or an ancestor to the original issue, a relational reference can be established. Otherwise the reference should always be aimed at the direct parent or child of the issue.
Steps three to ve consist of assigning additional information to the issues: rst labels, then people and lastly milestones. The labels are an essential part of the guideline and they are the main solution for creating visibility and status tracking. The guideline does not explicitly state what exact labels should be used rather it states possible categories for them. The categories are to be chosen based on the needs of the project and they may vary. There are a total of six categories suggested by the guideline: the type of the issue, the subtype of the task, status, requirement level, priority and miscellaneous. The guideline recommends that every category has its distinctive color with a unique shading for every single label. A short pre x in the beginning of each label depicting the category it belongs to complements the color coding. Generally there should always be a maximum of one label per category assigned to an issue, the miscellaneous labels being an exception but the important thing is that the categories exist and are used appropriately. After the labels comes assigning people (assignees) who are responsible for the implementation of the issue. They are linked directly to the issue.
The use of milestones is recommended and they complement the status and priority categories of the labels. The exact way to use the milestones is up to the development team. The guideline suggests that they can be used to represent iterations or groups of tasks covering some wider topic or feature.
The sixth step is publishing the issue. The seventh instructs the creator of the issue to update the references of other issues. When an issue is created and references updated successfully, it starts its own lifecycle. 4.3
Status tracking and tracing requirements are the core activities of RM. We have already created a base for them in the previous sections.
The traceability is mainly gained by the naming conventions and references, but also the labels from the type and subtype categories enhance it. The status tracking however relies on milestones and labels, like status, priority and miscellaneous.
The monitoring of these aspects requires lters. Even though they can not cover every scenario they are quite powerful, especially since the lters are a part of the URL, so bookmarking the most used lter combinations is possible. The required lter combinations is determined by what kind of information is relevant to di erent team members. Developers should be aware of all the issues that mention them and the issues directly assigned to them. Especially the priority and milestone information is relevant. Project managers should pay attention to every task currently worked with. This includes following milestone deadlines and task list progression if the issues contain them. Also issues needing special actions - like ones agged \blocked" - must be dealt with without a delay to keep the work ow going. 4.4
The wiki has already been mentioned in the issue creation. Depending on how much information is attached directly to the issue, the wiki is an excellent alternative for lengthier data masses. As it is within the repository, the convenience is increased due to an easy access. Should the wiki be utilized, establishing a logic structure inside it is recommended. The structure itself does not concern the guideline as long as it is consistent and logical. A careful attention should be kept to avoid situations where the wiki's data contradicts issues'.
The repository o ers some interesting interactions like referencing an issue from a commit message is possible. This is special feature of GitHub. Therefore to enhance visibility, developers are encouraged to always reference the issues their commit a ects. This creates an automatic comment to the issue's comment section, making the link between the commit and the issue more visible and traceable. 4.5
During the lifecycle of the issue, it is going to be updated in several ways: changing labels, assigning milestones, assigning people, commenting, referencing it from commit messages and closing it. Stakeholder communication regarding issues is a common update action. The challenge is that the communication can occur in multiple media. These interactions can cause changes to the issues' content. It is imperative that in such cases, the issue is immediately updated to re ect the changes: the descriptions of the issues must always be up to date. This guarantees that the latest and best knowledge is easy to nd. It is encouraged to use the comment area of an issue for discussion.
A crucial note is that users should be careful when deleting old information. By doing so the traceability is compromised. However the descriptions should not contain unnecessary information. The old information should be moved from the issue to a suitable page in the wiki. As important as it is to keep the description updated, is to make sure that the labels are used and updated. The importance of the labels is to visualize issues and di erent aspects of them in one view. Should the labels be misused or not updated, an unnecessary waste is generated. Letting the information get old causes mistrust towards the guideline and may lead for rejecting its practices. It also interferes with the RM and its objectives. 5
The guideline was evaluated in a student project given in the School of Information Sciences at the University of Tampere in 2013. The project lasted nine months, and had four developers and three project managers from whom one had to drop out during the project. None of the team had earlier experience with GitHub's issue tracker, though two of them had used GitHub. The team was multicultural and used English for the communication.
The goal of the project was to produce a mobile puzzle game which introduces the concept of computer science to school applicants. Due to a requirement of an open source development GitHub was chosen as a version control platform. At the beginning of the case study the team was accustomed to the platform. They also received the rst version of the guideline. Couple of weeks later the team received a shorter document summarizing the key aspects of the guideline. The team was responsible of deploying the guideline. We observed the usage from three perspectives: watching the team's actions in GitHub, surveying their internal communication and attending the meetings the team had with the customer. In the end of the project an online survey was lled by the team with di erent sets of questions for developers and managers.
Several important observations were made from the case study. The managers were little lazy to bring the requirements to the issue tracker and convert them to tasks. When this was nally conducted the project had already gone a good way. This meant that some of the traceability and status tracking were inherently lost. As the team consisted of mainly inexperienced students, they put more emphasize on the actual implementation than on the RM. This was also re ected on how the team perceived the whole issue tracker. One of the developers commented \I think the management of tasks and requirements is the role of the managers, { Managers should just ddle with the requirements." The rush with the deadlines also meant that the team skipped or neglected some parts of the guideline. For example issue descriptions were incomplete, issue references were neglected and the label categories were used too liberally. However the whole team felt that they had followed the guideline and it in fact did help them to achieve a more coherent RM process: \I believe it was very e cient", \Overall, the guideline was useful and logical, I did not nd any inherent aws in it.".
The guideline was evolved from the rst version published in October 2013 in a slideshow format. The purpose was to iteratively develop the guideline based on the feedback we received from the case study from October 2013 to May 2014. A few things were altered. The structure of the guideline was reformatted to make it more logical and readable. The discussion whether subtasks should be used was widened. We realized that there are valid situations where a main task coupled with a task list is enough. Therefore better arguments for and against of the subtasks were made, highlighting that the relevant information must be easily displayed whatever the chosen approach is. The rst version leaned towards the expectation that there is a strict division between who creates and handles issues and the rest of the team. The guideline and RM are everyone's responsibility and everyone's contribution is valuable, so the guideline was changed to put more emphasis on the whole team. The guideline failed to note the powerfulness of the milestones. With added examples users should be able to identify additional purposes for them that could help monitoring issues. Maintaining the issues received a new note about preserving the old information, especially about disregarding it. Tracing requirements becomes hard should the initial situation get lost. A new recommendation was that the issues should be closed with an accompanying comment to clarify why the issue was closed. In the case study there were a lot of issues closed without an apparent reason. This uncertainty was also partially due to somewhat disorganized use of the labels. Therefore the up-to-date labels are even more highlighted. Creating the special issues like enhancement proposals and bug reports has been clari ed to distinct how the guideline expects them to be used. 5.1
The purpose of the guideline was to o er a set of recommendations and practices
for the RM in GitHub's environment. Individual sections from the guideline can
be used as such but it is advisable to use it as a whole. Some room is left
for customization to preserve the versatility. The guideline aims to complement
the four areas of RM: change control, version control, requirements tracing and
requirements status tracking [
The guideline is a collection of practices and recommendations working together towards a consistent RM process. The guideline requires a knowledge of using GitHub, especially the repository, issue tracker and wiki. Using GFM is advised in the issues and wiki.
Before starting to work with issues, some preparations must be made. The labels, their categories and their color coding are to be decided. Overall naming conventions with the issues must be agreed on. Generally it is ideal to go through the guideline's practices and decide how they are applied into the project. Without a commitment from the whole team, the guideline loses its e ectiveness.
The team should appoint somebody responsible for the RM. This does not exempt the team from the RM. The purpose of the appointment is to have a person who can attend questions regarding the issue tracker, guideline and issues.
The guideline does not take a stand when it comes to requirements engineering processes occurring before the RM. They can be conducted by whatever means necessary for the project's scope and type. As new requirements are identi ed they are gradually created into the issue tracker. The prefered way is that the requirements are immediately put into the issue tracker. Postponing this delays the implementation. As soon as the requirements are in the issue tracker the team can start splitting them into tasks. When the rst tasks are ready the implementation can begin. The requirements are to be split in the order of priority to generate the best business value.
Creating requirements and tasks is usually an ongoing process and happens throughout the whole project. When the rst tasks are under work, they must be monitored, maintained and updated. 5.2
The following list will summarize the key aspects enhancing the objectives of
the RM and the principles of the Lean as introduced by Poppendiecks' [
Change control. Working and successful change control requires that there is a way to get an overview of how di erent requirements and their implementations and components relate to each other. This greatly helps solving the impacts of the proposed change. A special issue type the enhancement proposal gives a convenient way for formally proposing changes and tracking their life span: does the proposed change get implemented, is it further evaluated or even completely rejected. Of course, in an agile environment, changes don't always follow a formal path. The guideline enforces that information contained in the issues is always up to date.
Version control. The issue tracker itself holds all the requirements together. Every issue is given an unambiguous identi cation number by GitHub that can be used for referencing the issue. Versioning itself is not directly supported so the guideline suggests that the old information is not erased, but preserved somewhere else. The naming conventions and type labels are there for identifying purposes.
Requirements tracing. Separating requirements and concrete tasks and establishing a hierarchy between each issue creates a clear structure for tracing requirements and links they have. This strongly requires that the references in the descriptions are used and maintained properly. The aforementioned naming conventions also help identifying the relations between the issues.
Status tracking. The labels are the best way to accomplish the status tracking. The suggested categories are crafted so that tracking requirements and their tasks is as straightforward as possible. The drawback is that the labels are mainly toggled with tasks, not with requirements so the status tracking of requirements must be carried out through tasks.
Eliminating waste. Descriptions with enough information and an encouragement for a free speech in comments aim to generate more knowledge for the whole team. This contributes towards learning how to produce value more efciently. Avoiding unnecessary waiting sharing knowledge and using labels are suggested. The processes of the guideline are narrowed down and are inherently simple. They are also exible, which makes them more suitable for various situations. Splitting requirements to small pieces increases the possibility that unrequired extra features are detected and rejected.
Optimizing the whole. This is more like an attitude of the team and cannot be created by this kind of guideline. Sharing knowledge and discussing it increases the insight to the customer's mind and thus makes it easier to comprehend the whole picture.
Building quality in. The customer's needs must be understood and openly collaborated and communicated. Information sharing, keeping everything visible and actively using commenting are ways the guideline proposes.
Learning constantly. Sharing and absorbing both information and knowledge is best way to ful ll this principle. The splitting of requirements in small pieces forces the team to truly get a better understanding of the domain.
to implement making the fast delivery possible. Feedback and communication should occur all the time further improving the delivery and its quality. Deferring commitment requires the best available information. Keeping issues up to date and openly discussing them enhances this.
Respecting people. The guideline aims for empowering the whole team. They are the ones to use the issue tracker, and they all should have an interest on what is happening there. The guideline does not restrict who can do what. How well the empowerment succeeds is based on whether the parent organization supports giving the decision power to the development teams. 6
The aim of this article was to present a semi-formal guideline for conducting the RM process using only the tools provided by GitHub. To prove that the guideline is applicable and working, a case study was conducted. The guideline was evaluated on how well it supports the RM objectives and the lean principles.
As far as the research shows, this is an unique topic: similar guidelines for
GitHub platform with a properly surveyed case study could not be identi ed.
There exist several blog posts about thoughts and suggestions of using the issue
tracker, but none of them approached the topic as systematically. These blog
posts also lacked the evaluation of their usefulness [
For the science, the guideline is interesting because it combines the lean principles into the RM. This is also an area that is covered by very few studies.
The evaluation of the guideline gives more insight on how the RM can be coupled with the lean principles.
For the practitioners the guideline provides considerable, systematic and well documented instructions for using the issue tracker to handle the RM in a project that uses GitHub. The guideline is also evaluated by the case study, and though the study consisted of only a student project, its feedback was very positive. The case study project group felt that the guideline helped them achieve a more consistent RM process. By comparing the guideline against the lean principles we have showed that the guideline is well suited for the agile approach.
The guideline was created to be usable in a wide array of projects, though it is required that the project utilizes some agile approach. Therefore the biggest factor for not using the guideline is the chosen development process of a project. The practices and suggestions of the guideline are designed to be easily understood and adopted for establishing a good base for the RM. This is especially bene cial for agile projects that tend to bury the RM below an iterative development. As GitHub could be considered a programmer-friendly platform, handling the RM in the same place can lower the threshold of developers to participate and take more active role in it.
Like with any agile practices, the users are left with the responsibility to follow the instructions as they see t. This can cause a problem, if users try to cherry pick the concepts and leave out others. A selective use can greatly diminish the usability and results achieved by the guideline. The guideline leaves room for customization to preserve versatility but this means that instruction contain some vagueness.
There are some limitations concerning this article. The topic is very speci c which makes it unique but at the same time di cult to generalize. The RM has certain objectives and accomplishing them depends on the tools at disposal. With GitHub we have a limited set of features but on some other platform the tools and their usage may be completely di erent. Although the evaluation combines the RM and lean principles, it wraps around the guideline's practices and tools o ered by GitHub.
The case study was relatively limited in scope. The project was a student project that lasted nine months. The problem with students is that they tend to lack the experience present in professional software projects. As the project was carried out during the university semester the students also had other course to attend to, leaving relatively small amount of time to work with the project. The team was multicultural and this posed a minor problem with communication: English was used as the communication language but it was not native to any of the project members.
The guideline would greatly bene t from a larger case study involving projects with di erent settings and sizes. A wider case study would make it easier to further evaluate the core ideas of the guideline and how well they achieve their objectives. It could also highlight the situational contexts the guideline manages the best. Projects with experienced team members could give better facts to support di erent kind of approaches.
Overall the guideline achieved its goal: creating instructions for an agile requirements management process utilizing only GitHub's own tools. This is backed up by the case study and critical assertion of guideline's practices and GitHub's features.