CSE Software Development Standards
Scrum Board
User Stories
You will need to create a card in your scrum board for each user story. Each user story card documents exactly 1 potential feature in your program. Below is an example of a user story and then an explanation of each of the required elements.
† (title) contains the user story text. It should only contain the text of the user story. The text must follow the user story template: "As a role, I want action so that observable outcome". The role provides insight as to why this feature is important, the action describes what the role does to trigger the feature, and the observable outcome+ describes how the role knows the feature worked.
‡ (description) contains all of the acceptance tests for the story. All of the acceptance tests needed for this story should be written in the description area. Each acceptance test must be labeled and then followed by a numbered list of steps to take. Add a blank line between each of the tests. These tests will be run by an untrained user, so make certain you specify all the inputs that need to be entered and exact details of what they should see.
* (tags) "User Story" should be added to the card when the card is created. The current sprint should be added as a tag when the story is added to the "Planned" list. Ideally stories will be completed in the sprint in which it is started. When a story cannot be completed by the end of the sprint, it will have to carry over to the next sprint. In these cases, do NOT remove the original sprint tag, but instead __have the card include tags from the original sprint and the new sprint.
§ (dependencies) Each user story Is Blocked By all of the tasks that were created to implement the story. User stories need to have at least 1 (and almost always more than 1) task as a dependency. User stories never block nor are they blocked by other user stories.
(Not shown in this image) Comments can be added in the activity portion of the card to provide updates on this user story.
Tasks
Each task should also be created as a card on the scrum board. Below is an image on an example task and this is followed by an explanation of the required elements.
† (title) contains a brief summary of the task. It should only contain a summary of the task. There is no required template to follow and technical language is acceptable. A developer just joining the group should be able to figure out what the task will do from this summary.
‡ (description) contains all of the task tests for the story. All of the task tests needed for this task should be written out. Each task test must be labeled and there should be a blank line between each test. If unit tests are being used, then list the name(s) of the file. If the task tests use step-by-step instructions, each step should be numbered. These tests will be run by a developer, so jargon and technical details are expected. Be certain to specify all of the details about what to do or what should be verified in that test.
* (tags) should identifying this card as containing a task. The specific tags used for tasks will vary by course, but at no time should there be more than 1 type of task tag. When a task is added to the "Planned" list, it should also have the current sprint added as a tag. Ideally tasks will be completed in the sprint in which it is started. When a task cannot be completed by the end of the sprint, it will usually carry over to the next sprint. In these cases, do NOT remove the original sprint tag, but instead __have the card include tags from the original sprint and the new sprint.
# (members) specifies the student(s) responsible for completing this task. These assignments are usually made by the PM. Student(s) should add themselves in the member area of every task they were assigned by the PM immediately after the meeting. Students can choose to complete additional tasks by adding themselves in the member area, but only if those tasks are in the "Planned" list and are not assigned to anyone else. Removing a student from the member area or adding additional students to the member area is very rare and only by specific instruction of the PM.
¤ (branch) specifies the name of the branch off of dev was created for this task when the task was moved to the "In Progress" list and required adding or updating files. Branches are not required if the task neither creates, deletes, nor modifies files in the repo.
§ (dependencies) link the task to the user story for which it was created. Every task Blocks exactly 1 user story. A task should neither block nor be blocked by another task.
(Not shown in this image) Card comments MUST be used to record the URLs and findings in any research-related tasks. Comments can also be used to provide updates or communicate information in all tasks.
Lists in the Scrum Board
The lists will already be setup for you in the scrum board in the PMTool. The name of each list and order that they should appear on your scrum board will match those in the image below:
† (Backlog) Contains cards for any user stories and tasks that have been created but not yet included in a sprints. Because it is important to capture ideas as we have them, we will create user stories for every feature we can imagine. This also means that cards in the Backlog do not have to be complete or correct. As their ideas are fleshed out, the cards should be fixed and tests added or modified. Cards can only be moved into Backlog if it is in the Planned list and it is the very start of a sprint.
‡ (Planned) User stories should have a full set of acceptance tests and task cards should have convincing task tests before they are added to the Planned list. At the start of each sprint, all of the user stories and tasks which the team intends to complete in the current sprint should be moved into Planned. Cards should have the current sprint tag added to them when they are moved into the Planned list. Cards should NEVER be moved from Planned to Backlog in the middle of a sprint.
* (In Progress) Cards are moved into In Progress as soon as you begin working on them. When moving task cards into In Progress, you will need to add all of the people assigned to that card as members. You should also create and attach the repo branch created for this task (but only if it creates or modifies files). If the task has a branch, there should be at least 1 commit between when a task is moved into In Progress and when it is moved into Testing. Cards should never be moved from In Progress back to Planned or Backlog.
# (Testing) Cards are in Testing while their developer is running the task tests or acceptance tests prior to moving them to Completed. This is an important, necessary step in the process to document that the tests were actually run. If 1 or more tests fail, the card should be moved back to In Progress and the bugs should be fixed.
¤ (Complete) Cards are moved to Complete only after running and passing all of the card's acceptance tests or task tests. Moving a card to Complete is usually the last time a teammember moves the card.
§ (Closed) Typically only the PM will move user stories and tasks from the Completed list to Closed. In very special circumstances, the PM may request that the team do this just prior to the end of a sprint.
Github
Branches in Github
At the start of your project, you will need to create a dev branch off of the main branch. Your project's main branch is used to hold the latest release of your project. The current sprint's completed tasks will be added to the dev branch. AT NO TIME SHOULD YOU EVER MAKE A COMMIT DIRECTLY TO THE main OR dev BRANCHES.
It is important that the dev branch only contains code and documents from tasks which have been completed and tested. At the end of each sprint, your PM "releases" a new version of your project by creating and approving a pull request which merges the dev branch into the main branch.
When starting work on a task that will create, update, or remove files from the repo, you will must create a branch from the dev branch for your task. The new branch's name should contain the task's card number and be meaningful. This allows your manager, your manager's manager, and other outsiders to understand the work you are doing and why you are doing it. Making regular commits in this branch documents your progress for your manager, insures others can follow your thought process in this work, and limits information loss due to a power outage or lottery win. Do NOT wait to finish your code before committing – broken code cannot harm anyone else since they will be working on different branches. Once your work is complete and passes all of the task tests, move the task card to the “Completed” list and use a pull request to merge the branch back into the dev branch.
The history of branches and commits can be seen in GitHub by selecting the "Insights" tab, and then clicking on "Network" from the menu bar on the left. An example of a good use of branches can be seen below:
Commits in Github
It is expected that students will make regular commits as they are working on a file. In addition to ensuring progress gets saved, regular commits allow others to recreate their process and understand the decisions they made while coding. Frequently pushing changes to the server (and pulling down any updates) also keeps merge conflicts to a minimum and simplifies the cleanup process when it occurs.
Below is an image showing a sample commit using the GitHub web interface. Using this interface is NOT recommended, but it is shown here because it provides a good visual to explain the standards used:
† (subject) This should be under 50 characters and give a brief overview of why the commit matters. Since you are working on 1 task at a time and are making frequent commits, the commit should only contain work for 1 task and be made in that task's branch. If this commit finishes the code, move the task to the Testing pipeline and start your testing. Remember that the audience for your commit messages are your boss and the people who will need to update and support this code, so focus on the information they will need to know.
‡ (description) This is optional, but can be used if you need more than the summary to document this commit. If the commit breaks existing code or has any important side-effects, document those effects here and explain why these changes are valuable. Remember that the audience for your commit messages are your boss and the people who will need to update and support this code, so focus on the information they will need to know.