Week 4 [Feb 4]

There are no tutorials or lecture this week due to CNY.

However, do continue to make progress on the project front!

We will be adding you all to nusCS2113-AY1819S2 github org. Please accept the invitation sent by GitHub.
- You need to be a member of the org for some of the future module activities.
- If you did not receive the invitation link, you can use the link https://github.com/orgs/nusCS2113-AY1819S2/invitation.
Get started on the project (i.e., defining your project direction and requirements). Try to do at least step 1 of mid-v1.0 project milestone immediately after CNY, and try to finish the remainder by the end of the week.
A heads up: next week is going to be HEAVY 😨 as it has two graded tasks (and some spill over topics from CNY week) -- both require significant team efforts and a substantial time to complete. We urge you all to make full use of this week to prepare yourself for that challenge. In particular,
- Try to reach mid-v1.0 fully by the end of this week i.e., complete all 3 steps.
- If you are not familiar with Git and GitHub, complete this week's topics related to Git and GitHub. Next week's topics need that knowledge.

[W4.1] OOP: Polymorphism

[W4.2] Requirements analysis
[W4.3] Techniques for gathering requirements
[W4.4] Techniques for specifying requirements

[W4.5] RCS: Workflows

[W4.1] OOP: Polymorphism

Polymorphism

[W4.1a] Paradigms → Object Oriented Programming → Polymorphism → What

Can explain OOP polymorphism

Polymorphism:

The ability of different objects to respond, each in its own way, to identical messages is called polymorphism. _{-- Object-Oriented Programming with Objective-C, Apple}

Polymorphism allows you to write code targeting superclass objects, use that code on subclass objects, and achieve possibly different results based on the actual class of the object.

Assume classes Cat and Dog are both subclasses of the Animal class. You can write code targeting Animal objects and use that code on Cat and Dog objects, achieving possibly different results based on whether it is a Cat object or a Dog object. Some examples:

Declare an array of type Animal and still be able to store Dog and Cat objects in it.
Define a method that takes an Animal object as a parameter and yet be able to pass Dog and Cat objects to it.
Call a method on a Dog or a Cat object as if it is an Animal object (i.e., without knowing whether it is a Dog object or a Cat object) and get a different response from it based on its actual class e.g., call the Animal class' method speak() on object a and get a Meow as the return value if a is a Cat object and Woof if it is a Dog object.

Polymorphism literally means "ability to take many forms".

[W4.1b] Paradigms → Object Oriented Programming → Inheritance → Overriding

Can explain method overriding

Method overriding is when a sub-class changes the behavior inherited from the parent class by re-implementing the method. Overridden methods have the same name, same type signature, and same return type.

Consider the following case of EvaluationReport class inheriting the Report class:

`Report` methods	`EvaluationReport` methods	Overrides?
`print()`	`print()`	Yes
`write(String)`	`write(String)`	Yes
`read():String`	`read(int):String`	No. Reason: the two methods have different signatures; This is a case of overloading (rather than overriding).

Paradigms → Object Oriented Programming → Inheritance →

Overloading

Method overloading is when there are multiple methods with the same name but different type signatures. Overloading is used to indicate that multiple operations do similar things but take different parameters.

Type Signature: The type signature of an operation is the type sequence of the parameters. The return type and parameter names are not part of the type signature. However, the parameter order is significant.

Method	Type Signature
`int add(int X, int Y)`	`(int, int)`
`void add(int A, int B)`	`(int, int)`
`void m(int X, double Y)`	`(int, double)`
`void m(double X, int Y)`	`(double, int)`

In the case below, the calculate method is overloaded because the two methods have the same name but different type signatures (String) and (int)

calculate(String): void
calculate(int): void

Which of these methods override another method? A is the parent class. B inherits A.

Explanation: Method overriding requires a method in a child class to use the same method name and same parameter sequence used by one of its ancestors

[W4.1c] C++ to Java → Inheritance → Polymorphism

Can use polymorphism in Java

Java is a strongly-typed language which means the code works with only the object types that it targets.

The following code PetShelter keeps a list of Cat objects and make them speak. The code will not work with any other type, for example, Dog objects.

public class PetShelter {
    private static Cat[] cats = new Cat[]{
            new Cat("Mittens"),
            new Cat("Snowball")};

    public static void main(String[] args) {
        for (Cat c: cats){
            System.out.println(c.speak());
        }
    }
}

Mittens: Meow
Snowball: Meow

public class Cat {
    public Cat(String name) {
        super(name);
    }

    public String speak() {
        return name + ": Meow";
    }
}

This strong-typing can lead to unnecessary verbosity caused by repetitive similar code that do similar things with different object types.

If the PetShelter is to keep both cats and dogs, you'll need two arrays and two loops:

public class PetShelter {
    private static Cat[] cats = new Cat[]{
            new Cat("Mittens"),
            new Cat("Snowball")};
    private static Dog[] dogs = new Dog[]{
            new Dog("Spot")};

    public static void main(String[] args) {
        for (Cat c: cats){
            System.out.println(c.speak());
        }
        for(Dog d: dogs){
            System.out.println(d.speak());
        }
    }
}

Mittens: Meow
Snowball: Meow
Spot: Woof

public class Dog {
    public Dog(String name) {
        super(name);
    }

    public String speak() {
        return name + ": Woof";
    }
}

A better way is to take advantage of polymorphism to write code that targets a superclass but works with any subclass objects.

The PetShelter2 use one data structure to keep both types of animals and one loop to make them speak. The code targets the Animal superclass (assuming Cat and Dog inherits from the Animal class) instead of repeating the code for each animal type.

public class PetShelter2 {
    private static Animal[] animals = new Animal[]{
            new Cat("Mittens"),
            new Cat("Snowball"),
            new Dog("Spot")};

    public static void main(String[] args) {
        for (Animal a: animals){
            System.out.println(a.speak());
        }
    }
}

Mittens: Meow
Snowball: Meow
Spot: Woof

public class Animal {

    protected String name;

    public Animal(String name){
        this.name = name;
    }
    public String speak(){
        return name;
    }
}

public class Cat extends Animal {
    public Cat(String name) {
        super(name);
    }

    @Override
    public String speak() {
        return name + ": Meow";
    }
}

public class Dog extends Animal {
    public Dog(String name) {
        super(name);
    }

    @Override
    public String speak() {
        return name + ": Woof";
    }
}

Explanation: Because Java supports polymorphism, you can store both Cat and Dog objects in an array of Animal objects. Similarly, you can call the speak method on any Animal object (as done in the loop) and yet get different behavior from Cat objects and Dog objects.

💡 Suggestion: try to add an Animal object (e.g., new Animal("Unnamed")) to the animals array and see what happens.

Polymorphic code is better in several ways:

It is shorter.
It is simpler.
It is more flexible (in the above example, the main method will work even if we add more animal types).

The Main class below keeps a list of Circle and Rectangle objects and prints the area (as an int value) of each shape when requested.

Add the missing variables/methods to the code below so that it produces the output given.

public class Main {
    //TODO add your methods here

    public static void main(String[] args) {
        addShape(new Circle(5));
        addShape(new Rectangle(3, 4));
        addShape(new Circle(10));
        printAreas();
        addShape(new Rectangle(4, 4));
        printAreas();
    }
}

Circle class and Rectangle class is given below but you'll need to add a parent class Shape:

public class Circle {

    private int radius;

    public Circle(int radius) {
        this.radius = radius;
    }

    public int area() {
        return (int)(Math.PI * radius * radius);
    }
}

public class Rectangle {
    private int height;
    private int width;

    public Rectangle(int height, int width){
        this.height = height;
        this.width = width;
    }

    public int area() {
        return height * width;
    }
}

💡 You may use an array of size 100 to store the shapes.

public class Main {
    private static Shape[] shapes = new Shape[100];
    private static int shapeCount = 0;

    public static void addShape(Shape s){
        shapes[shapeCount] = s;
        shapeCount++;
    }

    // ...

}

This exercise continues from the TaskManager Level1 exercise quoted above.

Enhance your TaskManager program in the following ways.

A. Add support for two types of tasks:

ToDo : a task to do someday
Deadline: a task to be done by a specific deadline

Both types keeps an internal flag to indicate if the task is done. The flag is initially set to false.

Here is an example output:

Welcome to TaskManager-Level2!
Your task? todo submit report
Tasks in the list: 1
Your task? deadline write report /by this Friday 4pm
Tasks in the list: 2
Your task? todo read textbook
Tasks in the list: 3
Your task? deadline return textbook /by Sunday
Tasks in the list: 4
Your task? print
Tasks:
[1] description: submit report
    is done? No
[2] description: write report
    is done? No
do by: this Friday 4pm
[3] description: read textbook
    is done? No
[4] description: return textbook
    is done? No
    do by: Sunday
Your task? exit
Bye!

Changes to the behavior:

add task description: adds the task description to the task list
todo task description: adds to the task list a todo task with the given task description
deadline task description /by deadline description: adds to the task list a deadline task with the given task description and with the deadline description

Suggestion:

Make the Todo class inherit from Task class, and make Deadline task inherit from Todo class.
Use polymorphism to store both types of tasks in an array of Task type and use one loop to print both types of tasks.

B. Add support for semi-automated regression testing using input/output redirection.

Quality Assurance → Testing → Test Automation →

Automated Testing of CLI Apps

A simple way to semi-automate testing of a CLI(Command Line Interface) app is by using input/output re-direction.

First, we feed the app with a sequence of test inputs that is stored in a file while redirecting the output to another file.
Next, we compare the actual output file with another file containing the expected output.

Let us assume we are testing a CLI app called AddressBook. Here are the detailed steps:

Store the test input in the text file input.txt.

add Valid Name p/12345 valid@email.butNoPrefix
add Valid Name 12345 e/valid@email.butPhonePrefixMissing

Store the output we expect from the SUT in another text file expected.txt.

Command: || [add Valid Name p/12345 valid@email.butNoPrefix]
Invalid command format: add 

Command: || [add Valid Name 12345 e/valid@email.butPhonePrefixMissing]
Invalid command format: add

Run the program as given below, which will redirect the text in input.txt as the input to AddressBook and similarly, will redirect the output of AddressBook to a text file output.txt. Note that this does not require any code changes to AddressBook.
```
java AddressBook < input.txt > output.txt
```
- 💡 The way to run a CLI program differs based on the language.
  e.g., In Python, assuming the code is in AddressBook.py file, use the command
  python AddressBook.py < input.txt > output.txt
- 💡 If you are using Windows, use a normal command window to run the app, not a Power Shell window.
More on the > operator and the < operator. tangential
A CLI program takes input from the keyboard and outputs to the console. That is because those two are default input and output streams, respectively. But you can change that behavior using < and > operators. For example, if you run AddressBook in a command window, the output will be shown in the console, but if you run it like this,
```
java AddressBook > output.txt 
```
the Operating System then creates a file output.txt and stores the output in that file instead of displaying it in the console. No file I/O coding is required. Similarly, adding < input.txt (or any other filename) makes the OS redirect the contents of the file as input to the program, as if the user typed the content of the file one line at a time.
Resources:
- Using command redirection operators in Windows
Next, we compare output.txt with the expected.txt. This can be done using a utility such as Windows FC (i.e. File Compare) command, Unix diff command, or a GUI tool such as WinMerge.
```
FC output.txt expected.txt
```

Note that the above technique is only suitable when testing CLI apps, and only if the exact output can be predetermined. If the output varies from one run to the other (e.g. it contains a time stamp), this technique will not work. In those cases we need more sophisticated ways of automating tests.

CLI App: An application that has a Command Line Interface. i.e. user interacts with the app by typing in commands.

import java.util.Scanner;

public class Main {
    static Scanner in = new Scanner(System.in);
    static Task[] tasks = new Task[100];
    static int taskCount = 0;

    public static void main(String[] args) {
        printWelcome();
        String line;

        boolean isExit = false;
        while (!isExit) {
            line = getInput();
            String command = line.split(" ")[0];
            switch (command) {
                case "exit":
                case "":
                    isExit = true;
                    break;
                case "todo":
                    addTodo(line);
                    break;
                case "deadline":
                    addDeadline(line);
                    break;
                case "print":
                    printTasks();
                    break;
                default:
                    printError();
            }
        }
        exit();

    }

    private static void addTodo(String line) {
        tasks[taskCount] = new Todo(line.substring("todo".length()).trim());
        taskCount++;
        System.out.println("Tasks in the list: " + taskCount);
    }

  // ...

    private static void printTasks() {
        System.out.println("Tasks:");
        for (int i = 0; i < taskCount; i++) {
            System.out.println("[" + (i + 1) + "] " + tasks[i]);
        }
    }
}

Abstract Classes

[W4.1d] Paradigms → Object Oriented Programming → Inheritance → Abstract Classes and Methods

Can implement abstract classes

Abstract Class: A class declared as an abstract class cannot be instantiated, but they can be subclassed.

You can use declare a class as abstract when a class is merely a representation of commonalities among its subclasses in which case it does not make sense to instantiate objects of that class.

The Animal class that exist as a generalization of its subclasses Cat, Dog, Horse, Tiger etc. can be declared as abstract because it does not make sense to instantiate an Animal object.

Abstract Method: An abstract method is a method signature without a method implementation.

The move method of the Animal class is likely to be an abstract method as it is not possible to implement a move method at the Animal class level to fit all subclasses because each animal type can move in a different way.

A class that has an abstract method becomes an abstract class because the class definition is incomplete (due to the missing method body) and it is not possible to create objects using an incomplete class definition.

Even a class that does not have any abstract methods can be declared as an abstract class.

[W4.1e] Tools → UML → Class Diagrams → Abstract Classes → What

Can interpret abstract classes in class diagrams

You can use italics or {abstract} (preferred) keyword to denote abstract classes/methods.

Example:

[W4.1f] C++ to Java → Inheritance → Abstract Classes and Methods

Can use abstract classes and methods

In Java, an abstract method is declared with the keyword abstract and given without an implementation. If a class includes abstract methods, then the class itself must be declared abstract.

The speak method in this Animal class is abstract. Note how the method signature ends with a semicolon and there is no method body. This makes sense as the implementation of the speak method depends on the type of the animal and it is meaningless to provide a common implementation for all animal types.

public abstract class Animal {

    protected String name;

    public Animal(String name){
        this.name = name;
    }
    public abstract String speak();
}

As one method of the class is abstract, the class itself is abstract.

An abstract class is declared with the keyword abstract. Abstract classes can be used as reference type but cannot be instantiated.

This Account class has been declared as abstract although it does not have any abstract methods. Attempting to instantiate Account objects will result in a compile error.

public abstract class Account {

    int number;

    void close(){
        //...
    }
}

Account a; OK to use as a type
a = new Account(); Compile error!

When an abstract class is subclassed, the subclass should provides implementations for all of the abstract methods in its superclass or else the subclass must also be declared abstract.

The Feline class below inherits from the abstract class Animal but it does not provide an implementation for the abstract method speak. As a result, the Feline class needs to be abstract too.

public abstract class Feline extends Animal {
    public Feline(String name) {
        super(name);
    }

}

The DomesticCat class inherits the abstract Feline class and provides the implementation for the abstract method speak. As a result, it need not be declared abstract.

public class DomesticCat extends Feline {
    public DomesticCat(String name) {
        super(name);
    }

    @Override
    public String speak() {
        return "Meow";
    }
}

Animal a = new Feline("Mittens"); Compile error! Feline is abstract.

Animal a = new DomesticCat("Mittens"); OK. DomesticCat can be instantiated and assigned to a variable of Animal type (the assignment is allowed by polymorphism).

Oracle’s Java Tutorials: Abstract Methods and Classes

The Main class below keeps a list of Circle and Rectangle objects and prints the area (as an int value) of each shape when requested.

public class Main {
    private static Shape[] shapes = new Shape[100];
    private static int shapeCount = 0;

    public static void addShape(Shape s){
        shapes[shapeCount] = s;
        shapeCount++;
    }

    public static void printAreas(){
        for (int i = 0; i < shapeCount; i++){
            shapes[i].print();
        }
    }

    public static void main(String[] args) {
        addShape(new Circle(5));
        addShape(new Rectangle(3, 4));
        addShape(new Circle(10));
        addShape(new Rectangle(4, 4));
        printAreas();
    }
}

Circle of area 78
Rectangle of area 12
Circle of area 314
Rectangle of area 16

Circle class and Rectangle class is given below:

public class Circle extends Shape {

    private int radius;

    public Circle(int radius) {
        this.radius = radius;
    }

    @Override
    public int area() {
        return (int)(Math.PI * radius * radius);
    }

    @Override
    public void print() {
        System.out.println("Circle of area " + area());
    }
}

public class Rectangle extends Shape {
    private int height;
    private int width;

    public Rectangle(int height, int width){
        this.height = height;
        this.width = width;
    }

    @Override
    public int area() {
        return height * width;
    }

    @Override
    public void print() {
        System.out.println("Rectangle of area " + area());
    }
}

Add the missing Shape class as an abstract class with two abstract methods.

public abstract class Shape {

    public abstract int area();
    // ...
}

Choose the correct statements about Java abstract classes and concrete classes.

a. A concrete class can contain an abstract method.
b. An abstract class can contain concrete methods.
c. An abstract class need not contain any concrete methods.
d. An abstract class cannot be instantiated.

(b)(c)(d)

Explanation: A concrete class cannot contain even a single abstract method.

Interfaces

[W4.1g] Paradigms → Object Oriented Programming → Inheritance → Interfaces

Can explain interfaces

An interface is a behavior specification i.e. a collection of method specifications. If a class implements the interface, it means the class is able to support the behaviors specified by the said interface.

There are a number of situations in software engineering when it is important for disparate groups of programmers to agree to a "contract" that spells out how their software interacts. Each group should be able to write their code without any knowledge of how the other group's code is written. Generally speaking, interfaces are such contracts. _{--Oracle Docs on Java}

Suppose SalariedStaff is an interface that contains two methods setSalary(int) and getSalary(). AcademicStaff can declare itself as implementing the SalariedStaff interface, which means the AcademicStaff class must implement all the methods specified by the SalariedStaff interface i.e., setSalary(int) and getSalary().

A class implementing an interface results in an is-a relationship, just like in class inheritance.

In the example above, AcademicStaff is a SalariedStaff. An AcademicStaff object can be used anywhere a SalariedStaff object is expected e.g. SalariedStaff ss = new AcademicStaff().

[W4.1h] Tools → UML → Class Diagrams → Interfaces → Interfaces

Can interpret interfaces in class diagrams

An interface is shown similar to a class with an additional keyword << interface >>. When a class implements an interface, it is shown similar to class inheritance except a dashed line is used instead of a solid line.

The AcademicStaff and the AdminStaff classes implement the SalariedStaff interface.

[W4.1i] C++ to Java → Inheritance → Interfaces

Can use interfaces in Java

The text given in this section borrows some explanations and code examples from the -- Java Tutorial.

In Java, an interface is a reference type, similar to a class, mainly containing method signatures. Defining an interface is similar to creating a new class except it uses the keyword interface in place of class.

Here is an interface named DrivableVehicle that defines methods needed to drive a vehicle.

public interface DrivableVehicle {
    void turn(Direction direction);
    void changeLanes(Direction direction);
    void signalTurn(Direction direction, boolean signalOn);
    // more method signatures
}

Note that the method signatures have no braces and are terminated with a semicolon.

Interfaces cannot be instantiated—they can only be implemented by classes. When an instantiable class implements an interface, indicated by the keyword implements, it provides a method body for each of the methods declared in the interface.

Here is how a class CarModelX can implement the DrivableVehicle interface.

public class CarModelX implements DrivableVehicle {

    @Override
    public void turn(Direction direction) {
       // implementation
    }

    // implementation of other methods
}

An interface can be used as a type e.g., DrivableVechile dv = new CarModelX();.

Interfaces can inherit from other interfaces using the extends keyword, similar to a class inheriting another.

Here is an interface named SelfDrivableVehicle that inherits the DrivableVehicle interface.

public interface SelfDrivableVehicle extends DrivableVehicle {
   void goToAutoPilotMode();
}

Note that the method signatures have no braces and are terminated with a semicolon.

Furthermore, Java allows multiple inheritance among interfaces. A Java interface can inherit multiple other interfaces. A Java class can implement multiple interfaces (and inherit from one class).

The design below is allowed by Java. In case you are not familiar with UML notation used: solid lines indicate normal inheritance; dashed lines indicate interface inheritance; the triangle points to the parent.

Staff interface inherits (note the solid lines) the interfaces TaxPayer and Citizen.
TA class implements both Student interface and the Staff interface.
Because of point 1 above, TA class has to implement all methods in the interfaces TaxPayer and Citizen.
Because of points 1,2,3, a TA is a Staff, is a TaxPayer and is a Citizen.

Interfaces can also contain constants and static methods.

C++ to Java → Miscellaneous Topics →

Constants

Java does not directly support constants. The convention is to use a static final variable where a constant is needed. The static modifier causes the variable to be available without instantiating an object. The final modifier causes the variable to be unchangeable. Java constants are normally declared in ALL CAPS separated by underscores.

Here is an example of a constant named MAX_BALANCE which can be accessed as Account.MAX_BALANCE.

public class Account{

  public static final double MAX_BALANCE = 1000000.0;

}

Math.PI is an example constant that comes with Java.

This example adds a constant MAX_SPEED and a static method isSpeedAllowed to the interface DrivableVehicle.

public interface DrivableVehicle {

    int MAX_SPEED = 150;

    static boolean isSpeedAllowed(int speed){
        return speed <= MAX_SPEED;
    }

    void turn(Direction direction);
    void changeLanes(Direction direction);
    void signalTurn(Direction direction, boolean signalOn);
    // more method signatures
}

Interfaces can contain default method implementations and nested types. They are not covered here.

The Main class below passes a list of Printable objects (i.e., objects that implement the Printable interface) for another method to be printed.

public class Main {

    public static void printObjects(Printable[] items) {
        for (Printable p : items) {
            p.print();
        }
    }

    public static void main(String[] args) {
        Printable[] printableItems = new Printable[]{
                new Circle(5),
                new Rectangle(3, 4),
                new Person("James Cook")};

        printObjects(printableItems);
    }
}

Circle of area 78
Rectangle of area 12
Person of name James Cook

Classes Shape, Circle, and Rectangle are given below:

public abstract class Shape {

    public abstract int area();
}

public class Circle extends Shape implements Printable {

    private int radius;

    public Circle(int radius) {
        this.radius = radius;
    }

    @Override
    public int area() {
        return (int)(Math.PI * radius * radius);
    }

    @Override
    public void print() {
        System.out.println("Circle of area " + area());
    }
}

public class Rectangle extends Shape implements Printable {
    private int height;
    private int width;

    public Rectangle(int height, int width){
        this.height = height;
        this.width = width;
    }

    @Override
    public int area() {
        return height * width;
    }

    @Override
    public void print() {
        System.out.println("Rectangle of area " + area());
    }
}

Add the missing Printable interface. Add the missing methods of the Person class given below.

public class Person implements Printable {

    private String name;

    // todo: add missing methods
}

public interface Printable {
    //...
}

[W4.2] Requirements analysis

[W4.2a] Requirements → Requirements → Introduction

Can explain requirements

A software requirement specifies a need to be fulfilled by the software product.

A software project may be,

a brown-field project i.e., develop a product to replace/update an existing software product
a green-field project i.e., develop a totally new system with no precedent

In either case, requirements need to be gathered, analyzed, specified, and managed.

Requirements come from stakeholders.

Stakeholder: A party that is potentially affected by the software project. e.g. users, sponsors, developers, interest groups, government agencies, etc.

Identifying requirements is often not easy. For example, stakeholders may not be aware of their precise needs, may not know how to communicate their requirements correctly, may not be willing to spend effort in identifying requirements, etc.

[W4.2b] Requirements → Requirements → Non-Functional Requirements

Can explain non-functional requirements

There are two kinds of requirements:

Functional requirements specify what the system should do.
Non-functional requirements specify the constraints under which system is developed and operated.

Some examples of non-functional requirement categories:

Data requirements e.g. size, volatility, persistency etc.,
Environment requirements e.g. technical environment in which system would operate or need to be compatible with.
Accessibility, Capacity, Compliance with regulations, Documentation, Disaster recovery, Efficiency, Extensibility, Fault tolerance, Interoperability, Maintainability, Privacy, Portability, Quality, Reliability, Response time, Robustness, Scalability, Security, Stability, Testability, and more ...

Business/domain rules: e.g. the size of the minefield cannot be smaller than five.
Constraints: e.g. the system should be backward compatible with data produced by earlier versions of the system; system testers are available only during the last month of the project; the total project cost should not exceed $1.5 million.
Technical requirements: e.g. the system should work on both 32-bit and 64-bit environments.
Performance requirements: e.g. the system should respond within two seconds.
Quality requirements: e.g. the system should be usable by a novice who has never carried out an online purchase.
Process requirements: e.g. the project is expected to adhere to a schedule that delivers a feature set every one month.
Notes about project scope: e.g. the product is not required to handle the printing of reports.
Any other noteworthy points: e.g. the game should not use images deemed offensive to those injured in real mine clearing activities.

We may have to spend an extra effort in digging NFRs out as early as possible because,

NFRs are easier to miss e.g., stakeholders tend to think of functional requirements first
sometimes NFRs are critical to the success of the software. E.g. A web application that is too slow or that has low security is unlikely to succeed even if it has all the right functionality.

Given below are some requirements of TEAMMATES (an online peer evaluation system for education). Which one of these are non-functional requirements?

a. The response to any use action should become visible within 5 seconds.
b. The application admin should be able to view a log of user activities.
c. The source code should be open source.
d. A course should be able to have up to 2000 students.
e. As a student user, I can view details of my team members so that I can know who they are.
f. The user interface should be intuitive enough for users who are not IT-savvy.
g. The product is offered as a free online service.

(a)(c)(d)(f)(g)

Explanation: (b) are (e) are functions available for a specific user types. Therefore, they are functional requirements. (a), (c), (d), (f) and (g) are either constraints on functionality or constraints on how the project is done, both of which are considered non-functional requirements.

[W4.2c] Requirements → Requirements → Prioritizing Requirements

Can explain prioritizing requirements

Requirements can be prioritized based the importance and urgency, while keeping in mind the constraints of schedule, budget, staff resources, quality goals, and other constraints.

A common approach is to group requirements into priority categories. Note that all such scales are subjective, and stakeholders define the meaning of each level in the scale for the project at hand.

An example scheme for categorizing requirements:

Essential: The product must have this requirement fulfilled or else it does not get user acceptance
Typical: Most similar systems have this feature although the product can survive without it.
Novel: New features that could differentiate this product from the rest.

Other schemes:

High, Medium, Low
Must-have, Nice-to-have, Unlikely-to-have
Level 0, Level 1, Level 2, ...

Some requirements can be discarded if they are considered ‘out of scope ’.

The requirement given below is for a Calendar application. Stakeholder of the software (e.g. product designers) might decide the following requirement is not in the scope of the software.

The software records the actual time taken by each task and show the difference between the actual and scheduled time for the task.

[W4.2d] Requirements → Requirements → Quality of Requirements

Can explain quality of requirements

Here are some characteristics of well-defined requirements ^{[📖 zielczynski]}:

Unambiguous
Testable (verifiable)
Clear (concise, terse, simple, precise)
Correct
Understandable
Feasible (realistic, possible)
Independent
Atomic
Necessary
Implementation-free (i.e. abstract)

Besides these criteria for individual requirements, the set of requirements as a whole should be

Consistent
Non-redundant
Complete

Peter Zielczynski, Requirements Management Using IBM Rational RequisitePro, IBM Press, 2008

[W4.3] Techniques for gathering requirements

[W4.3a] Requirements → Gathering Requirements → Brainstorming

Can explain brainstorming

Brainstorming: A group activity designed to generate a large number of diverse and creative ideas for the solution of a problem.

In a brainstorming session there are no "bad" ideas. The aim is to generate ideas; not to validate them. Brainstorming encourages you to "think outside the box" and put "crazy" ideas on the table without fear of rejection.

What is the key characteristic about brainstorming?

a. There should be at least 5 participants.
b. All ideas are welcome. There are no bad ideas.
c. Only the best people in the team should take part.
d. They are a good way to eliminate bad ideas.

(b)

[W4.3b] Requirements → Gathering Requirements → Product Surveys

Can explain product surveys

Studying existing products can unearth shortcomings of existing solutions that can be addressed by a new product. Product manuals and other forms of technical documentation of an existing system can be a good way to learn about how the existing solutions work.

When developing a game for a mobile device, a look at a similar PC game can give insight into the kind of features and interactions the mobile game can offer.

[W4.3c] Requirements → Gathering Requirements → Observation

Can explain observation

Observing users in their natural work environment can uncover product requirements. Usage data of an existing system can also be used to gather information about how an existing system is being used, which can help in building a better replacement e.g. to find the situations where the user makes mistakes when using the current system.

[W4.3d] Requirements → Gathering Requirements → User Surveys

Can explain user surveys

Surveys can be used to solicit responses and opinions from a large number of stakeholders regarding a current product or a new product.

[W4.3e] Requirements → Gathering Requirements → Interviews

Can explain interviews

Interviewing stakeholders and domain experts can produce useful information that project requirements.

Domain Expert : An expert of a discipline to which the product is connected e.g., for a software used for Accounting, a domain expert is someone who is an expert of Accounting.

[W4.3f] Requirements → Gathering Requirements → Focus Groups

Can explain focus groups

_[source]

Focus groups are a kind of informal interview within an interactive group setting. A group of people (e.g. potential users, beta testers) are asked about their understanding of a specific issue, process, product, advertisement, etc.

: How do focus groups work? - Hector Lanz tangential

[W4.4] Techniques for specifying requirements

User Stories

[W4.4a] Requirements → Specifying Requirements → User Stories → Introduction

Can write simple user stories

User story: User stories are short, simple descriptions of a feature told from the perspective of the person who desires the new capability, usually a user or customer of the system. _{[Mike Cohn]}

A common format for writing user stories is:

User story format: As a {user type/role} I can {function} so that {benefit}

Examples (from a Learning Management System):

As a student, I can download files uploaded by lecturers, so that I can get my own copy of the files
As a lecturer, I can create discussion forums, so that students can discuss things online
As a tutor, I can print attendance sheets, so that I can take attendance during the class

We can write user stories on index cards or sticky notes, and arrange on walls or tables, to facilitate planning and discussion. Alternatively, we can use a software (e.g., GitHub Project Boards, Trello, Google Docs, ...) to manage user stories digitally.

^{[credit: https://www.flickr.com/photos/jakuza/2682466984/]}

^{[credit: https://www.flickr.com/photos/jakuza/with/2726048607/]}

^{[credit: https://commons.wikimedia.org/wiki/File:User_Story_Map_in_Action.png]}

a. They are based on stories users tell about similar systems
b. They are written from the user/customer perspective
c. They are always written in some physical medium such as index cards or sticky notes

a. Reason: Despite the name, user stories are not related to 'stories' about the software.
b.
c. Reason: It is possible to use software to record user stories. When the team members are not co-located this may be the only option.

Critique the following user story taken from a software project to build an e-commerce website.

As a developer, I want to use Python to implement the software, so that we can resue existing Python modules.

Refer to the definition of a user story.

This user story is not written from the perspective of the user/customer.

Bill wants you to build a Human Resource Management (HRM) system. He mentions that the system will help employees to view their own leave balance. What are the user stories you can extract from that statement?

Remember to follow the correct format when writing user stories.

User story format: As a {user type/role} I can {function} so that {benefit}

As an employee, I can view my leave balance, so that I can know how many leave days I have left.

Note: the {benefit} part may vary as it is not specifically mentioned in the question.

[W4.4b] Requirements → Specifying Requirements → User Stories → Details

[W4.4c] Requirements → Specifying Requirements → User Stories → Usage

Can use user stories to manage requirements of project

User stories capture user requirements in a way that is convenient for scoping, estimation and scheduling.

[User stories] strongly shift the focus from writing about features to discussing them. In fact, these discussions are more important than whatever text is written. _{[Mike Cohn, MountainGoat Software 🔗]}

User stories differ from traditional requirements specifications mainly in the level of detail. User stories should only provide enough details to make a reasonably low risk estimate of how long the user story will take to implement. When the time comes to implement the user story, the developers will meet with the customer face-to-face to work out a more detailed description of the requirements. [more...]

User stories can capture non-functional requirements too because even NFRs must benefit some stakeholder.

Requirements → Requirements →

Non-Functional Requirements

There are two kinds of requirements:

Functional requirements specify what the system should do.
Non-functional requirements specify the constraints under which system is developed and operated.

Some examples of non-functional requirement categories:

Data requirements e.g. size, volatility, persistency etc.,
Environment requirements e.g. technical environment in which system would operate or need to be compatible with.
Accessibility, Capacity, Compliance with regulations, Documentation, Disaster recovery, Efficiency, Extensibility, Fault tolerance, Interoperability, Maintainability, Privacy, Portability, Quality, Reliability, Response time, Robustness, Scalability, Security, Stability, Testability, and more ...

Business/domain rules: e.g. the size of the minefield cannot be smaller than five.
Constraints: e.g. the system should be backward compatible with data produced by earlier versions of the system; system testers are available only during the last month of the project; the total project cost should not exceed $1.5 million.
Technical requirements: e.g. the system should work on both 32-bit and 64-bit environments.
Performance requirements: e.g. the system should respond within two seconds.
Quality requirements: e.g. the system should be usable by a novice who has never carried out an online purchase.
Process requirements: e.g. the project is expected to adhere to a schedule that delivers a feature set every one month.
Notes about project scope: e.g. the product is not required to handle the printing of reports.
Any other noteworthy points: e.g. the game should not use images deemed offensive to those injured in real mine clearing activities.

We may have to spend an extra effort in digging NFRs out as early as possible because,

NFRs are easier to miss e.g., stakeholders tend to think of functional requirements first
sometimes NFRs are critical to the success of the software. E.g. A web application that is too slow or that has low security is unlikely to succeed even if it has all the right functionality.

Given below are some requirements of TEAMMATES (an online peer evaluation system for education). Which one of these are non-functional requirements?

a. The response to any use action should become visible within 5 seconds.
b. The application admin should be able to view a log of user activities.
c. The source code should be open source.
d. A course should be able to have up to 2000 students.
e. As a student user, I can view details of my team members so that I can know who they are.
f. The user interface should be intuitive enough for users who are not IT-savvy.
g. The product is offered as a free online service.

(a)(c)(d)(f)(g)

An example of a NFR captured as a user story:

As a	I want to	so that
impatient user	to be able experience reasonable response time from the website while up to 1000 concurrent users are using it	I can use the app even when the traffic is at the maximum expected level

Given their lightweight nature, user stories are quite handy for recording requirements during early stages of requirements gathering.

💡 Here are some tips for using user stories for early stages of requirement gathering:

Define the target user:
Decide your target user's profile (e.g. a student, office worker, programmer, sales person) and work patterns (e.g. Does he work in groups or alone? Does he share his computer with others?). A clear understanding of the target user will help when deciding the importance of a user story. You can even give this user a name. e.g. Target user Jean is a university student studying in a non-IT field. She interacts with a lot of people due to her involvement in university clubs/societies. ...
Define the problem scope: Decide that exact problem you are going to solve for the target user. e.g. Help Jean keep track of all her school contacts
Don't be too hasty to discard 'unusual' user stories:
Those might make your product unique and stand out from the rest, at least for the target users.
Don't go into too much details:
For example, consider this user story: As a user, I want to see a list of tasks that needs my attention most at the present time, so that I pay attention to them first.
When discussing this user story, don't worry about what tasks should be considered needs my attention most at the present time. Those details can be worked out later.
Don't be biased by preconceived product ideas:
When you are at the stage of identifying user needs, clear your mind of ideas you have about what your end product will look like.
Don't discuss implementation details or whether you are actually going to implement it:
When gathering requirements, your decision is whether the user's need is important enough for you to want to fulfil it. Implementation details can be discussed later. If a user story turns out to be too difficult to implement later, you can always omit it from the implementation plan.

While use cases can be recorded on physical paper in the initial stages, an online tool is more suitable for longer-term management of user stories, especially if the team is not co-located.

You can create issues for each of the user stories and use a GitHub Project Board to sort them into categories.

Example Project Board:

Example Issue to represent a user story:

A video on GitHub Project Boards:

Example Google Sheet for recording user stories:

Example Trello Board for recording user stories:

This article by Mike Cohn from MountainGoatSoftware explains how to use user stories to capture NFRs.

Use Cases

[W4.4d] Requirements → Specifying Requirements → Use Cases → Introduction

Can explain use cases

Use Case: A description of a set of sequences of actions, including variants, that a system performs to yield an observable result of value to an actor.[ 📖 : uml-user-guideThe Unified Modeling Language User Guide, 2e, G Booch, J Rumbaugh, and I Jacobson ]

Actor: An actor (in a use case) is a role played by a user. An actor can be a human or another system. Actors are not part of the system; they reside outside the system.

A use case describes an interaction between the user and the system for a specific functionality of the system.

System: ATM
Actor: Customer
Use Case: Check account balance
1. User inserts an ATM card
2. ATM prompts for PIN
3. User enters PIN
4. ATM prompts for withdrawal amount
5. User enters the amount
6. ATM ejects the ATM card and issues cash
7. User collects the card and the cash.

System: A Learning Management System (LMS)
Actor: Student
Use Case: Upload file
1. Student requests to upload file
2. LMS requests for the file location
3. Student specifies the file location
4. LMS uploads the file

UML includes a diagram type called use case diagrams that can illustrate use cases of a system visually , providing a visual ‘table of contents’ of the use cases of a system. In the example below, note how use cases are shown as ovals and user roles relevant to each use case are shown as stick figures connected to the corresponding ovals.

Use cases capture the functional requirements of a system.

[W4.4e] Requirements → Specifying Requirements → Use Cases → Identifying

Can use use cases to list functional requirements of a simple system

A use case is an interaction between a system and its actors.

Actors in Use Cases

Actor: An actor (in a use case) is a role played by a user. An actor can be a human or another system. Actors are not part of the system; they reside outside the system.

Some example actors for a Learning Management System

Actors: Guest, Student, Staff, Admin, ExamSys, LibSys.

A use case can involve multiple actors.

Software System: LearnSys
Use case: UC01 conduct survey
Actors: Staff, Student

An actor can be involved in many use cases.

Software System: LearnSys
Actor: Staff
Use cases: UC01 conduct survey, UC02 Set Up Course Schedule, UC03 Email Class, ...

A single person/system can play many roles.

Software System: LearnSys
Person: a student
Actors (or Roles): Student, Guest, Tutor

Many persons/systems can play a single role.

Software System: LearnSys
Actor(or role) : Student
Persons that can play this role : undergraduate student, graduate student, a staff member doing a part-time course, exchange student

Use cases can be specified at various levels of detail.

Consider the three use cases given below. Clearly, (a) is at a higher level than (b) and (b) is at a higher level than (c).

System: LearnSys
Use cases:
a. Conduct a survey
b. Take the survey
c. Answer survey question

💡 While modeling user-system interactions,

Start with high level use cases and progressively work toward lower level use cases.
Be mindful at which level of details you are working on and not to mix use cases of different levels.

Consider a simple movie ticket vending machine application. Every week, the theatre staff will enter the weekly schedule as well as ticket price for each show. A customer sees the schedule and the ticket price displayed at the machine. There is a slot to insert money, a keypad to enter a code for a movie, a code for the show time, and the number of tickets. A display shows the customer's balance inside the machine. A customer may choose to cancel a transaction before pressing the “buy” button. Printed tickets can be collected from a slot at the bottom of the machine. The machine also displays messages such as "Please enter more money”, “Request fewer tickets" or "SOLD OUT!”. Finally, a "Return Change" button allows the customer to get back his unspent money.

Draw a use case diagram for the above requirements.

Note that most of the details in the description are better given as part of the use case description rather than as low-level use cases in the diagram.

A software house wishes to automate its Quality Assurance division.

The system is to be used by Testers, Programmers and System Administrators. Only an administrator can create new users and assign tasks to programmers. Any tester can create a bug report, as well as set the status of a bug report as ‘closed’. Only a programmer can set the state of a bug report to ‘fixed’, but a programmer cannot set the status of a bug report to ‘closed’. Each tester is assigned just one task at a time. A task involves testing of a particular component for a particular customer. Tester must document the bugs they find. Each bug is given a unique identifier. Other information recorded about the bug is component id, severity, date and time reported, programmer who is assigned to fix it, date fixed, date retested and date closed. The system keeps track of which bugs are assigned to which programmer at any given time. It should be able to generate reports on the number of bugs found, fixed and closed e.g. number of bugs per component and per customer; number of bugs found by a particular tester ; number of bugs awaiting to be fixed; number of bugs awaiting to be retested; number of bugs awaiting to be assigned to programmers etc.

Develop a use case diagram to capture their requirements given below.

Explanation: The given description contains information not relevant to use case modeling. Furthermore, the description is not enough to complete the use case diagram All these are realities of real projects. However, the process of trying to create this use case diagram prompts us to investigate issues such as:

Is ‘edit bug report’ a use case or editing the bug report is covered by other use cases such as those for setting the status of bug reports? If it is indeed a separate use case, who are the actors of that use case?
Does ‘assign task’ simply means ‘assign bug report’ or is there any other type of tasks?
There was some mention about Customers and Components. Does the system have to support use cases for creating and maintaining details about those entities? For example, should we have a ‘create customer record’ use case?
Which actors can perform the ‘generate report’ use case? Are reports generated automatically by the system at a specific time or generated ‘on demand’ when users request to view them? Do we have to treat different types of reports as different use cases (in case some types of reports are restricted to some types of users)? The above diagram assumes (just for illustration) that the report is generated on demand and only the system admin can generate any report.

[W4.4f] Requirements → Specifying Requirements → Use Cases → Details

[W4.4g] Requirements → Specifying Requirements → Use Cases → Usage

Can optimize the use of use cases

You can use actor generalization in use case diagrams using a symbol similar to that of UML notation for inheritance.

In this example, actor Blogger can do all the use cases the actor Guest can do, as a result of the actor generalization relationship given in the diagram.

💡 Do not over-complicate use case diagrams by trying to include everything possible. A use case diagram is a brief summary of the use cases that is used as a starting point. Details of the use cases can be given in the use case descriptions.

Some include ‘System’ as an actor to indicate that something is done by the system itself without being initiated by a user or an external system.

The diagram below can be used to indicate that the system generates daily reports at midnight.

However, others argue that only use cases providing value to an external user/system should be shown in the use case diagram. For example, they argue that ‘view daily report’ should be the use case and generate daily report is not to be shown in the use case diagram because it is simply something the system has to do to support the view daily report use case.

We recommend that you follow the latter view (i.e. not to use System as a user). Limit use cases for modeling behaviors that involve an external actor.

UML is not very specific about the text contents of a use case. Hence, there are many styles for writing use cases. For example, the steps can be written as a continuous paragraph. Use cases should be easy to read. Note that there is no strict rule about writing all details of all steps or a need to use all the elements of a use case.

There are some advantages of documenting system requirements as use cases:

Because they use a simple notation and plain English descriptions, they are easy for users to understand and give feedback.
They decouple user intention from mechanism (note that use cases should not include UI-specific details), allowing the system designers more freedom to optimize how a functionality is provided to a user.
Identifying all possible extensions encourages us to consider all situations that a software product might face during its operation.
Separating typical scenarios from special cases encourages us to optimize the typical scenarios.

One of the main disadvantages of use cases is that they are not good for capturing requirements that does not involve a user interacting with the system. Hence, they should not be used as the sole means to specify requirements.

What are the advantages of using use cases (the textual form) for requirements modelling?

a. They can be fairly detailed but still natural enough for users for users to understand and give feedback.
b. The UI-independent nature of use case specification allows the system designers more freedom to decide how a functionality is provided to a user.
c. Extensions encourage us to consider all situations a software product might face during its operations.
d. They encourage us to identify and optimize the typical scenario of usage over exceptional usage scenarios.

(a) (b) (c) (d)

Which of these are correct?

a. Use case are not very suitable for capturing non-functional requirements.
b. Use case diagrams are less detailed than textual use cases.
c. Use cases are better than user stories.
d. Use cases can be expressed at different levels of abstraction.

(a)(b)(d)

Explanation: It is not correct to say one format is better than the other. It depends on the context.

Feature Lists

[W4.4h] Requirements → Specifying Requirements → Feature Lists → What

Can explain feature list

Feature List: A list of features of a product grouped according to some criteria such as aspect, priority, order of delivery, etc.

A sample feature list from a simple Minesweeper game (only a brief description has been provided to save space):

Basic play – Single player play.
Difficulty levels
- Medium-levels
- Advanced levels
Versus play – Two players can play against each other.
Timer – Additional fixed time restriction on the player.
...

Prose

[W4.4i] Requirements → Specifying Requirements → Prose → What

Can explain prose

A textual description (i.e. prose) can be used to describe requirements. Prose is especially useful when describing abstract ideas such as the vision of a product.

The product vision of the TEAMMATES Project given below is described using prose.

TEAMMATES aims to become the biggest student project in the world (biggest here refers to 'many contributors, many users, large code base, evolving over a long period'). Furthermore, it aims to serve as a training tool for Software Engineering students who want to learn SE skills in the context of a non-trivial real software product.

Avoid using lengthy prose to describe requirements; they can be hard to follow.

Prototyping

[W4.4j] Requirements → Gathering Requirements → Prototyping

Can explain prototyping

Prototype: A prototype is a mock up, a scaled down version, or a partial system constructed

to get users’ feedback.
to validate a technical concept (a "proof-of-concept" prototype).
to give a preview of what is to come, or to compare multiple alternatives on a small scale before committing fully to one alternative.
for early field-testing under controlled conditions.

Prototyping can uncover requirements, in particular, those related to how users interact with the system. UI prototypes are often used in brainstorming sessions, or in meetings with the users to get quick feedback from them.

^{[source: http://balsamiq.com/products/mockups]}

💡 Prototyping can be used for discovering as well as specifying requirements e.g. a UI prototype can serve as a specification of what to build.

Glossary

[W4.4k] Requirements → Specifying Requirements → Glossary → What

Can explain glossary

Glossary: A glossary serves to ensure that all stakeholders have a common understanding of the noteworthy terms, abbreviation, acronyms etc.

Here is a partial glossary from a variant of the Snakes and Ladders game:

Conditional square: A square that specifies a specific face value which a player has to throw before his/her piece can leave the square.
Normal square: a normal square does not have any conditions, snakes, or ladders in it.

Supplementary Requirements

[W4.4l] Requirements → Specifying Requirements → Supplementary Requirements → What

Can explain supplementary requirements

A supplementary requirements section can be used to capture requirements that do not fit elsewhere. Typically, this is where most Non Functional Requirements will be listed.

Requirements → Requirements →

Non-Functional Requirements

There are two kinds of requirements:

Functional requirements specify what the system should do.
Non-functional requirements specify the constraints under which system is developed and operated.

Some examples of non-functional requirement categories:

Data requirements e.g. size, volatility, persistency etc.,
Environment requirements e.g. technical environment in which system would operate or need to be compatible with.
Accessibility, Capacity, Compliance with regulations, Documentation, Disaster recovery, Efficiency, Extensibility, Fault tolerance, Interoperability, Maintainability, Privacy, Portability, Quality, Reliability, Response time, Robustness, Scalability, Security, Stability, Testability, and more ...

Business/domain rules: e.g. the size of the minefield cannot be smaller than five.
Constraints: e.g. the system should be backward compatible with data produced by earlier versions of the system; system testers are available only during the last month of the project; the total project cost should not exceed $1.5 million.
Technical requirements: e.g. the system should work on both 32-bit and 64-bit environments.
Performance requirements: e.g. the system should respond within two seconds.
Quality requirements: e.g. the system should be usable by a novice who has never carried out an online purchase.
Process requirements: e.g. the project is expected to adhere to a schedule that delivers a feature set every one month.
Notes about project scope: e.g. the product is not required to handle the printing of reports.
Any other noteworthy points: e.g. the game should not use images deemed offensive to those injured in real mine clearing activities.

We may have to spend an extra effort in digging NFRs out as early as possible because,

NFRs are easier to miss e.g., stakeholders tend to think of functional requirements first
sometimes NFRs are critical to the success of the software. E.g. A web application that is too slow or that has low security is unlikely to succeed even if it has all the right functionality.

Given below are some requirements of TEAMMATES (an online peer evaluation system for education). Which one of these are non-functional requirements?

a. The response to any use action should become visible within 5 seconds.
b. The application admin should be able to view a log of user activities.
c. The source code should be open source.
d. A course should be able to have up to 2000 students.
e. As a student user, I can view details of my team members so that I can know who they are.
f. The user interface should be intuitive enough for users who are not IT-savvy.
g. The product is offered as a free online service.

(a)(c)(d)(f)(g)

[W4.5] RCS: Workflows

Branching

[W4.5a] Project Management → Revision Control → Branching

Can explain branching

Branching is the process of evolving multiple versions of the software in parallel. For example, one team member can create a new branch and add an experimental feature to it while the rest of the team keeps working on another branch. Branches can be given names e.g. master, release, dev.

A branch can be merged into another branch. Merging usually result in a new commit that represents the changes done in the branch being merged.

Branching and merging

Merge conflicts happen when you try to merge two branches that had changed the same part of the code and the RCS software cannot decide which changes to keep. In those cases we have to ‘resolve’ those conflicts manually.

In the context of RCS, what is the branching? What is the need for branching?.

In the context of RCS, what is the merging branches? How can it lead to merge conflicts?.

[W4.5b] Tools → Git and GitHub → Branch

Can use Git branching

0. Observe that you are normally in the branch called master. For this, you can take any repo you have on your computer (e.g. a clone of the samplerepo-things).

git status

on branch master

1. Start a branch named feature1 and switch to the new branch.

Click on the Branch button on the main menu. In the next dialog, enter the branch name and click Create Branch

Note how the feature1 is indicated as the current branch.

You can use the branch command to create a new branch and the checkout command to switch to a specific branch.

git branch feature1
git checkout feature1

One-step shortcut to create a branch and switch to it at the same time:

git checkout –b feature1

2. Create some commits in the new branch. Just commit as per normal. Commits you add while on a certain branch will become part of that branch.

3. Switch to the master branch. Note how the changes you did in the feature1 branch are no longer in the working directory.

Double-click the master branch

git checkout master

4. Add a commit to the master branch. Let’s imagine it’s a bug fix.

5. Switch back to the feature1 branch (similar to step 3).

6. Merge the master branch to the feature1 branch, giving an end-result like the below. Also note how Git has created a merge commit.

Right-click on the master branch and choose merge master into the current branch. Click OK in the next dialog.

git merge master

Observe how the changes you did in the master branch (i.e. the imaginary bug fix) is now available even when you are in the feature1 branch.

7. Add another commit to the feature1 branch.

8. Switch to the master branch and add one more commit.

9. Merge feature1 to the master branch, giving and end-result like this:

Right-click on the feature1 branch and choose Merge....

git merge feature1

10. Create a new branch called add-countries, switch to it, and add some commits to it (similar to steps 1-2 above). You should have something like this now:

11. Go back to the master branch and merge the add-countries branch onto the master branch (similar to steps 8-9 above). While you might expect to see something like the below,

... you are likely to see something like this instead:

That is because Git does a fast forward merge if possible. Seeing that the master branch has not changed since you started the add-countries branch, Git has decided it is simpler to just put the commits of the add-countries branch in front of the master branch, without going into the trouble of creating an extra merge commit.

It is possible to force Git to create a merge commit even if fast forwarding is possible.

Tick the box shown below when you merge a branch:

Use the --no-ff switch (short for no fast forward):

git merge --no-ff add-countries

Merge conflicts

[W4.5c] Tools → Git and GitHub → Merge Conflicts

Can use Git to resolve merge conflicts

1. Start a branch named fix1 in a local repo. Create a commit that adds a line with some text to one of the files.

2. Switch back to master branch. Create a commit with a conflicting change i.e. it adds a line with some different text in the exact location the previous line was added.

3. Try to merge the fix1 branch onto the master branch. Git will pause mid-way during the merge and report a merge conflict. If you open the conflicted file, you will see something like this:

COLORS
------
blue
<<<<<<< HEAD
black
=======
green
>>>>>>> fix1
red
white

4. Observe how the conflicted part is marked between a line starting with <<<<<<< and a line starting with >>>>>>>, separated by another line starting with =======.

This is the conflicting part that is coming from the master branch:


<<<<<<< HEAD
black
=======

This is the conflicting part that is coming from the fix1 branch:


=======
green
>>>>>>> fix1

5. Resolve the conflict by editing the file. Let us assume you want to keep both lines in the merged version. You can modify the file to be like this:

COLORS
------
blue
black
green
red
white

6. Stage the changes, and commit.

Pull requests

[W4.5d] Tools → Git and GitHub → Create PRs

Can create PRs on GitHub

1. Fork the samplerepo-pr-practice onto your GitHub account. Clone it onto your computer.

2. Create a branch named add-intro in your clone. Add a couple of commits which adds/modifies an Introduction section to the README.md. Example:


# Introduction
Creating Pull Requsts (PRs) is needed when using RCS in a multi-person projects.
This repo can be used to practice creating PRs.

3. Push the add-intro branch to your fork.

git push origin add-intro

4. Create a Pull Request from the add-intro branch in your fork to the master branch of the same fork (i.e. your-user-name/samplerepo-pr-practice, not se-edu/samplerepo-pr-practice), as described below.

4a. Go to the GitHub page of your fork (i.e. https://github.com/{your_username}/samplerepo-pr-practice), click on the Pull Requests tab, and then click on New Pull Request button.

4b. Select base fork and head fork as follows:

base fork: your own fork (i.e. {your user name}/samplerepo-pr-practice, NOT se-edu/samplerepo-pr-practice)
head fork: your own fork.

The base fork is where changes should be applied. The head fork contains the changes you would like to be applied.

4c. (1) Set the base branch to master and head branch to add-intro, (2) confirm the diff contains the changes you propose to merge in this PR (i.e. confirm that you did not accidentally include extra commits in the branch), and (3) click the Create pull request button.

4d. (1) Set PR name, (2) set PR description, and (3) Click the Create pull request button.

A common newbie mistake when creating branch-based PRs is to mix commits of one PR with another. To learn how to avoid that mistake, you are encouraged to continue and create another PR as explained below.

5. In your local repo, create a new branch add-summary off the master branch.

When creating the new branch, it is very important that you switch back to the master branch first. If not, the new branch will be created off the current branch add-intro. And that is how you end up having commits of the first PR in the second PR as well.

6. Add a commit in the add-summary branch that adds a Summary section to the README.md, in exactly the same place you added the Introduction section earlier.

7. Push the add-summary to your fork and create a new PR similar to before.

GitHub's own documentation on creating a PR

[W4.5e] Tools → Git and GitHub → Manage PRs

Can review and merge PRs on GitHub

1. Go to GitHub page of your fork and review the add-intro PR you created previously in [Tools → Git & GitHub → Create PRs] to simulate the PR being reviewed by another developer, as explained below. Note that some features available to PR reviewers will be unavailable to you because you are also the author of the PR.

1. Fork the samplerepo-pr-practice onto your GitHub account. Clone it onto your computer.

2. Create a branch named add-intro in your clone. Add a couple of commits which adds/modifies an Introduction section to the README.md. Example:


# Introduction
Creating Pull Requsts (PRs) is needed when using RCS in a multi-person projects.
This repo can be used to practice creating PRs.

3. Push the add-intro branch to your fork.

git push origin add-intro

4a. Go to the GitHub page of your fork (i.e. https://github.com/{your_username}/samplerepo-pr-practice), click on the Pull Requests tab, and then click on New Pull Request button.

4b. Select base fork and head fork as follows:

base fork: your own fork (i.e. {your user name}/samplerepo-pr-practice, NOT se-edu/samplerepo-pr-practice)
head fork: your own fork.

The base fork is where changes should be applied. The head fork contains the changes you would like to be applied.

4d. (1) Set PR name, (2) set PR description, and (3) Click the Create pull request button.

5. In your local repo, create a new branch add-summary off the master branch.

6. Add a commit in the add-summary branch that adds a Summary section to the README.md, in exactly the same place you added the Introduction section earlier.

7. Push the add-summary to your fork and create a new PR similar to before.

GitHub's own documentation on creating a PR

1a. Go to the respective PR page and click on the Files changed tab. Hover over the line you want to comment on and click on the icon that appears on the left margin. That should create a text box for you to enter your comment.

1b. Enter some dummy comment and click on Start a review button.

1c. Add a few more comments in other places of the code.

1d. Click on the Review Changes button, enter an overall comment, and click on the Submit review button.

2. Update the PR to simulate revising the code based on reviewer comments. Add some more commits to the add-intro branch and push the new commits to the fork. Observe how the PR is updated automatically to reflect the new code.

3. Merge the PR. Go to the GitHub page of the respective PR, scroll to the bottom of the Conversation tab, and click on the Merge pull request button, followed by the Confirm merge button. You should see a Pull request successfully merged and closed message after the PR is merged.

4. Sync the local repo with the remote repo. Because of the merge you did on the GitHub, the master branch of your fork is now ahead of your local repo by one commit. To sync the local repo with the remote repo, pull the master branch to the local repo.

git checkout master
git pull origin master

Observe how the add-intro branch is now merged to the master branch in your local repo as well.

5. De-conflict the add-summary PR that you created earlier. Note that GitHub page for the add-summary PR is now showing a conflict (when you scroll to the bottom of that page, you should see a message This branch has conflicts that must be resolved). You can resolve it locally and update the PR accordingly, as explained below.

5a. Switch to the add-summary branch. To make that branch up-to-date with the master branch, merge the master branch to it, which will surface the merge conflict. Resolve it and complete the merge.

5b. Push the updated add-summary branch to the fork. That will remove the 'merge conflicts' warning in the GitHub page of the PR.

6. Merge the add-summary PR using the GitHub interface, similar to how you merged the previous PR.

Note that you could have merged the add-summary branch to the master branch locally before pushing it to GitHub. In that case, the PR will be merged on GitHub automatically to reflect that the branch has been merged already.

Workflows

[W4.5f] Project Management → Revision Control → DRCS vs CRCS

Can explain DRCS vs CRCS

RCS can be done in two ways: the centralized way and the distributed way.

Centralized RCS (CRCS for short)uses a central remote repo that is shared by the team. Team members download (‘pull’) and upload (‘push’) changes between their own local repositories and the central repository. Older RCS tools such as CVS and SVN support only this model. Note that these older RCS do not support the notion of a local repo either. Instead, they force users to do all the versioning with the remote repo.

The centralized RCS approach without any local repos (e.g., CVS, SVN)

Distributed RCS (DRCS for short, also known as Decentralized RCS) allows multiple remote repos and pulling and pushing can be done among them in arbitrary ways. The workflow can vary differently from team to team. For example, every team member can have his/her own remote repository in addition to their own local repository, as shown in the diagram below. Git and Mercurial are some prominent RCS tools that support the distributed approach.

The decentralized RCS approach

[W4.5g] Project Management → Revision Control → Forking Flow

Can explain forking workflow

In the forking workflow, the 'official' version of the software is kept in a remote repo designated as the 'main repo'. All team members fork the main repo create pull requests from their fork to the main repo.

To illustrate how the workflow goes, let’s assume Jean wants to fix a bug in the code. Here are the steps:

Jean creates a separate branch in her local repo and fixes the bug in that branch.
Jean pushes the branch to her fork.
Jean creates a pull request from that branch in her fork to the main repo.
Other members review Jean’s pull request.
If reviewers suggested any changes, Jean updates the PR accordingly.
When reviewers are satisfied with the PR, one of the members (usually the team lead or a designated 'maintainer' of the main repo) merges the PR, which brings Jean’s code to the main repo.
Other members, realizing there is new code in the upstream repo, sync their forks with the new upstream repo (i.e. the main repo). This is done by pulling the new code to their own local repo and pushing the updated code to their own fork.

A detailed explanation of the Forking Workflow - From Atlassian

[W4.5h] Tools → Git and GitHub → Forking Workflow

Can follow Forking Workflow

This activity is best done as a team. If you are learning this alone, you can simulate a team by using two different browsers to log into GitHub using two different accounts.

One member: set up the team org and the team repo.
- Create a GitHub organization for your team. The org name is up to you. We'll refer to this organization as team org from now on.
- Add a team called developers to your team org.
- Add your team members to the developers team.
- Fork se-edu/samplerepo-workflow-practice to your team org. We'll refer to this as the team repo.
- Add the forked repo to the developers team. Give write access.
Each team member: create PRs via own fork
- Fork that repo from your team org to your own GitHub account.
- Create a PR to add a file yourName.md (e.g. jonhDoe.md) containing a brief resume of yourself (branch → commit → push → create PR)
For each PR: review, update, and merge.
- A team member (not the PR author): Review the PR by adding comments (can be just dummy comments).
- PR author: Update the PR by pushing more commits to it, to simulate updating the PR based on review comments.
- Another team member: Merge the PR using the GitHub interface.
- All members: Sync your local repo (and your fork) with upstream repo. In this case, your upstream repo is the repo in your team org.
Create conflicting PRs.
- Each team member: Create a PR to add yourself under the Team Members section in the README.md.
- One member: in the master branch, remove John Doe and Jane Doe from the README.md, commit, and push to the main repo.
Merge conflicting PRs one at a time. Before merging a PR, you’ll have to resolve conflicts. Steps:
- [Optional] A member can inform the PR author (by posting a comment) that there is a conflict in the PR.
- PR author: Pull the master branch from the repo in your team org. Merge the pulled master branch to your PR branch. Resolve the merge conflict that crops up during the merge. Push the updated PR branch to your fork.
- Another member or the PR author: When GitHub does not indicate a conflict anymore, you can go ahead and merge the PR.

[W4.5i] Project Management → Revision Control → Feature Branch Flow

Can explain feature branch flow

Feature branch workflow is similar to forking workflow except there are no forks. Everyone is pushing/pulling from the same remote repo. The phrase feature branch is used because each new feature (or bug fix, or any other modification) is done in a separate branch and merged to master branch when ready.

A detailed explanation of the Feature Branch Workflow - From Atlassian

[W4.5j] Project Management → Revision Control → Centralized Flow

Can explain centralized flow

The centralized workflow is similar to the feature branch workflow except all changes are done in the master branch.

A detailed explanation of the Centralized Workflow - From Atlassian

Project Milestone: mid-v1.0

Decide on requirements (user stories, use cases, non-functional requirements).

💡 Given below are some guidance on the recommended progress at this point of the project (i.e., at week 4, which is the midway point of the milestone v1.0)

This is a good time to analyze requirements with a view to conceptualizing the next version of the product (i.e. v2.0).

Step 1 : Brainstorm user stories

Get together with your team members and brainstorm for user stories for the v2.0 of the product. Note that in the module project you will deliver only up to v1.4 but here you should consider up to v2.0 (i.e. beyond the module).
- It is ok to have more user stories than you can deliver in the project. Aim to create at least 30 user stories. Include all 'obvious' ones you can think of but also look for 'non obvious' ones that you think are likely to be missed by other teams.
- Refer [Textbook Specifying Requirements → UserStories → Usage → (section) Tips] for tips on how to use user stories in this task.
- You can write each user story in a piece of paper (e.g. yellow sticky note, index card, or just pieces of paper about the size of a playing card). Alternatively you can use an online tool (some examples given in [Textbook Specifying Requirements → UserStories → Usage → (panel) Tool Examples ]).
- Note that you should not 'evaluate' the value of user stories while doing the above. Reason: an important aspect of brainstorming is not judging the ideas generated.

Requirements → Specifying Requirements → User Stories →

Introduction

A common format for writing user stories is:

User story format: As a {user type/role} I can {function} so that {benefit}

Examples (from a Learning Management System):

As a student, I can download files uploaded by lecturers, so that I can get my own copy of the files
As a lecturer, I can create discussion forums, so that students can discuss things online
As a tutor, I can print attendance sheets, so that I can take attendance during the class

^{[credit: https://www.flickr.com/photos/jakuza/2682466984/]}

^{[credit: https://www.flickr.com/photos/jakuza/with/2726048607/]}

^{[credit: https://commons.wikimedia.org/wiki/File:User_Story_Map_in_Action.png]}

a. They are based on stories users tell about similar systems
b. They are written from the user/customer perspective
c. They are always written in some physical medium such as index cards or sticky notes

a. Reason: Despite the name, user stories are not related to 'stories' about the software.
b.
c. Reason: It is possible to use software to record user stories. When the team members are not co-located this may be the only option.

Critique the following user story taken from a software project to build an e-commerce website.

As a developer, I want to use Python to implement the software, so that we can resue existing Python modules.

Refer to the definition of a user story.

This user story is not written from the perspective of the user/customer.

Remember to follow the correct format when writing user stories.

User story format: As a {user type/role} I can {function} so that {benefit}

As an employee, I can view my leave balance, so that I can know how many leave days I have left.

Note: the {benefit} part may vary as it is not specifically mentioned in the question.

Given their lightweight nature, user stories are quite handy for recording requirements during early stages of requirements gathering.

💡 Here are some tips for using user stories for early stages of requirement gathering:

Define the target user:
Decide your target user's profile (e.g. a student, office worker, programmer, sales person) and work patterns (e.g. Does he work in groups or alone? Does he share his computer with others?). A clear understanding of the target user will help when deciding the importance of a user story. You can even give this user a name. e.g. Target user Jean is a university student studying in a non-IT field. She interacts with a lot of people due to her involvement in university clubs/societies. ...
Define the problem scope: Decide that exact problem you are going to solve for the target user. e.g. Help Jean keep track of all her school contacts
Don't be too hasty to discard 'unusual' user stories:
Those might make your product unique and stand out from the rest, at least for the target users.
Don't go into too much details:
For example, consider this user story: As a user, I want to see a list of tasks that needs my attention most at the present time, so that I pay attention to them first.
When discussing this user story, don't worry about what tasks should be considered needs my attention most at the present time. Those details can be worked out later.
Don't be biased by preconceived product ideas:
When you are at the stage of identifying user needs, clear your mind of ideas you have about what your end product will look like.
Don't discuss implementation details or whether you are actually going to implement it:
When gathering requirements, your decision is whether the user's need is important enough for you to want to fulfil it. Implementation details can be discussed later. If a user story turns out to be too difficult to implement later, you can always omit it from the implementation plan.

💡 Recommended: You can use GitHub issue tracker to manage user stories, but for that you need to set up your team's GitHub organization, project fork, and issue tracker first. Instructions for doing those steps are in the panel below.

Organization setup

Please follow the organization/repo name format precisely because we use scripts to download your code or else our scripts will not be able to detect your work.

After receiving your team ID, one team member should do the following steps:

Create a GitHub organization with the following details:
- Organization name : CS2113-AY1819S2-TEAM_ID. e.g. CS2113-AY1819S2-M11-1
- Plan: Open Source ($0/month)
Add members to the organization:
- Create a team called developers to your organization.
- Add your team members to the developers team.

Repo setup

Only one team member:

Fork either Address Book Level 3 or Address Book Level 4 to your team org.
Rename the forked repo as main. This repo (let's call it the team repo) is to be used as the repo for your project.
Ensure the issue tracker of your team repo is enabled. Reason: our bots will be posting your weekly progress reports on the issue tracker of your team repo.
Ensure your team members have the desired level of access to your team repo.
Enable Travis CI for the team repo.
Set up auto-publishing of docs. When set up correctly, your project website should be available via the URL https://nus-cs2113-ay1819s2-{team-id}.github.io/main e.g., https://cs2113-ay1819s2-w13-1.github.io/main/. This also requires you to enable the GitHub Pages feature of your team repo and configure it to serve the website from the gh-pages branch.
create a team PR for us to track your project progress: i.e., create a PR from your team repo master branch to [nuscs2113-AY1819S2/addressbook-level4] master branch. PR name: [Team ID] Product Name e.g., [T09-2] Contact List Pro. As you merge code to your team repo's master branch, this PR will auto-update to reflect how much your team's product has progressed. In the PR description @mention the other team members so that they get notified when the tutor adds comments to the PR.

All team members:

Watchthe main repo (created above) i.e., go to the repo and click on the watch button to subscribe to activities of the repo
Fork the main repo to your personal GitHub account.
Clone the fork to your Computer.
Recommended: Set it up as an Intellij project (follow the instructions in the Developer Guide carefully).
Set up the developer environment in your computer. You are recommended to use JDK 9 for AB-4 as some of the libraries used in AB-4 have not updated to support Java 10 yet. JDK 9 can be downloaded from the Java Archive.

Note that some of our download scripts depend on the following folder paths. Please do not alter those paths in your project.

/src/main
/src/test
/docs

Note: If you fork from Address Book Level 3, ensure that the folder structure is similar to the one in Address Book Level 4

Issue tracker setup

We recommend you configure the issue tracker of the main repo as follows:

Delete existing labels and add the following labels.
💡 Issue type labels are useful from the beginning of the project. The other labels are needed only when you start implementing the features.

Issue type labels:

type.Epic : A big feature which can be broken down into smaller stories e.g. search
type.Story : A user story
type.Enhancement: An enhancement to an existing story
type.Task : Something that needs to be done, but not a story, bug, or an epic. e.g. Move testing code into a new folder)
type.Bug : A bug

Status labels:

status.Ongoing : The issue is currently being worked on. note: remove this label before closing an issue.

Priority labels:

priority.High : Must do
priority.Medium : Nice to have
priority.Low : Unlikely to do

Bug Severity labels:

severity.Low : A flaw that is unlikely to affect normal operations of the product. Appears only in very rare situations and causes a minor inconvenience only.
severity.Medium : A flaw that causes occasional inconvenience to some users but they can continue to use the product.
severity.High : A flaw that affects most users and causes major problems for users. i.e., makes the product almost unusable for most users.

Create following milestones : v1.0, v1.1, v1.2, v1.3, v1.4,
You may configure other project settings as you wish. e.g. more labels, more milestones

Project Schedule Tracking

In general, use the issue tracker (Milestones, Issues, PRs, Tags, Releases, and Labels) for assigning, scheduling, and tracking all noteworthy project tasks, including user stories. Update the issue tracker regularly to reflect the current status of the project. You can also use GitHub's Projects feature to manage the project, but keep it linked to the issue tracker as much as you can.

Using Issues:

During the initial stages (latest by the start of v1.2):

Record each of the user stories you plan to deliver as an issue in the issue tracker. e.g. Title: As a user I can add a deadline
Description: ... so that I can keep track of my deadlines
Assign the type.* and priority.* labels to those issues.
Formalize the project plan by assigning relevant issues to the corresponding milestone.

From milestone v1.2:

Define project tasks as issues. When you start implementing a user story (or a feature), break it down to smaller tasks if necessary. Define reasonable sized, standalone tasks. Create issues for each of those tasks so that they can be tracked.e.g.
- A typical task should be able to done by one person, in a few hours.
  - Bad (reasons: not a one-person task, not small enough): Write the Developer Guide
  - Good: Update class diagram in the Developer Guide for v1.4
- There is no need to break things into VERY small tasks. Keep them as big as possible, but they should be no bigger than what you are going to assign a single person to do within a week. eg.,
  - Bad:Implementing parser (reason: too big).
  - Good:Implementing parser support for adding of floating tasks
- Do not track things taken for granted. e.g., push code to repo should not be a task to track. In the example given under the previous point, it is taken for granted that the owner will also (a) test the code and (b) push to the repo when it is ready. Those two need not be tracked as separate tasks.
- Write a descriptive title for the issue. e.g. Add support for the 'undo' command to the parser
  - Omit redundant details. In some cases, the issue title is enough to describe the task. In that case, no need to repeat it in the issue description. There is no need for well-crafted and detailed descriptions for tasks. A minimal description is enough. Similarly, labels such as priority can be omitted if you think they don't help you.
Assign tasks (i.e., issues) to the corresponding team members using the assignees field. Normally, there should be some ongoing tasks and some pending tasks against each team member at any point.
Optionally, you can use status.ongoing label to indicate issues currently ongoing.

Using Milestones:

We recommend you do proper milestone management starting from v1.2. Given below are the conditions to satisfy for a milestone to be considered properly managed:

Planning a Milestone:

Issues assigned to the milestone, team members assigned to issues: Used GitHub milestones to indicate which issues are to be handled for which milestone by assigning issues to suitable milestones. Also make sure those issues are assigned to team members. Note that you can change the milestone plan along the way as necessary.
Deadline set for the milestones (in the GitHub milestone). Your internal milestones can be set earlier than the deadlines we have set, to give you a buffer.

Wrapping up a Milestone:

A working product tagged with the correct tag (e.g. v1.2) and is pushed to the main repo
or a product release done on GitHub. A product release is optional for v1.2 but required from from v1.3. Click here to see an example release.
All tests passing on Travis for the version tagged/released.
Milestone updated to match the product i.e. all issues completed and PRs merged for the milestone should be assigned to the milestone. Incomplete issues/PRs should be moved to a future milestone.
Milestone closed.
If necessary, future milestones are revised based on what you experienced in the current milestone e.g. if you could not finish all issues assigned to the current milestone, it is a sign that you overestimated how much you can do in a week, which means you might want to reduce the issues assigned to future milestones to match that observation.

As a user I can add a task by specifying a task description only, so that I can record tasks that need to be done ‘some day’. As a user I can find upcoming tasks, so that I can decide what needs to be done soon. As a user I can delete a task, so that I can get rid of tasks that I no longer care to track. As a new user I can view more information about a particular command, so that I can learn how to use various commands. As an advanced user I can use shorter versions of a command, so that type a command faster.

Step 2: Prioritize the user stories

Suggested workflow:
- Take one user story at a time and get team member opinions about it.
- Based on the team consensus, put the story (i.e. the piece of paper) onto one of these three piles:
  - Must-Have : The product will be practically useless to the target user without this feature.
  - Nice-To-Have : The target user can benefit from this user story significantly but you are not certain if you'll have time to implement it.
  - Not-Useful : No significant benefit to the target user, or does not fit into the product vision.
- If using physical paper to record user stories: After all stories have been put in the above three piles, you can make a record of which stories are in the three piles.
Step 3: Document requirements of the product

Based on your user story categorization in the step above, given module requirements/constraints for the project, and the current state of the product, select which user stories you are likely to include in v2.0.

Document the following items using a convenient format (e.g., a GoogleDoc). Do not spend time on formatting the content nicely; reason: these will be ported to the actual Developer Guide in your project repo later.
💡 Some examples of these can be found in the AB4 Developer Guide.
- Target user profile, value proposition, and user stories: Update the target user profile and value proposition to match the project direction you have selected. Give a list of the user stories (and update/delete existing ones, if applicable), including priorities. This can include user stories considered but will not be included in the final product.
- Use cases: Give use cases (textual form) for a few representative user stories that need multiple steps to complete. e.g. Adding a tag to a person (assume the user needs to find the person first)
- Non-functional requirements:
  Note: Many of the project constraints mentioned above are NFRs. You can add more. e.g. performance requirements, usability requirements, scalability requirements, etc.
- Glossary: Define terms that are worth defining.
- [Optional]Product survey: Explore a few similar/related products and describe your findings i.e. Pros, cons, (from the target user's point of view).

Requirements → Specifying Requirements → Use Cases →

Introduction

Actor: An actor (in a use case) is a role played by a user. An actor can be a human or another system. Actors are not part of the system; they reside outside the system.

A use case describes an interaction between the user and the system for a specific functionality of the system.

System: ATM
Actor: Customer
Use Case: Check account balance
1. User inserts an ATM card
2. ATM prompts for PIN
3. User enters PIN
4. ATM prompts for withdrawal amount
5. User enters the amount
6. ATM ejects the ATM card and issues cash
7. User collects the card and the cash.

System: A Learning Management System (LMS)
Actor: Student
Use Case: Upload file
1. Student requests to upload file
2. LMS requests for the file location
3. Student specifies the file location
4. LMS uploads the file

Use cases capture the functional requirements of a system.

Requirements → Requirements →

Non-Functional Requirements

There are two kinds of requirements:

Functional requirements specify what the system should do.
Non-functional requirements specify the constraints under which system is developed and operated.

Some examples of non-functional requirement categories:

Data requirements e.g. size, volatility, persistency etc.,
Environment requirements e.g. technical environment in which system would operate or need to be compatible with.
Accessibility, Capacity, Compliance with regulations, Documentation, Disaster recovery, Efficiency, Extensibility, Fault tolerance, Interoperability, Maintainability, Privacy, Portability, Quality, Reliability, Response time, Robustness, Scalability, Security, Stability, Testability, and more ...

Business/domain rules: e.g. the size of the minefield cannot be smaller than five.
Constraints: e.g. the system should be backward compatible with data produced by earlier versions of the system; system testers are available only during the last month of the project; the total project cost should not exceed $1.5 million.
Technical requirements: e.g. the system should work on both 32-bit and 64-bit environments.
Performance requirements: e.g. the system should respond within two seconds.
Quality requirements: e.g. the system should be usable by a novice who has never carried out an online purchase.
Process requirements: e.g. the project is expected to adhere to a schedule that delivers a feature set every one month.
Notes about project scope: e.g. the product is not required to handle the printing of reports.
Any other noteworthy points: e.g. the game should not use images deemed offensive to those injured in real mine clearing activities.

We may have to spend an extra effort in digging NFRs out as early as possible because,

NFRs are easier to miss e.g., stakeholders tend to think of functional requirements first
sometimes NFRs are critical to the success of the software. E.g. A web application that is too slow or that has low security is unlikely to succeed even if it has all the right functionality.

Given below are some requirements of TEAMMATES (an online peer evaluation system for education). Which one of these are non-functional requirements?

a. The response to any use action should become visible within 5 seconds.
b. The application admin should be able to view a log of user activities.
c. The source code should be open source.
d. A course should be able to have up to 2000 students.
e. As a student user, I can view details of my team members so that I can know who they are.
f. The user interface should be intuitive enough for users who are not IT-savvy.
g. The product is offered as a free online service.

(a)(c)(d)(f)(g)

At this point we would like to ensure that you are able to create branch-based PRs without accidentally mixing commits between PRs (a common mistake) Therefore, we strongly encourage you to learn the topic: W4.5 -> Pull requests before attempting other exercises.

There are no tutorials this week due to CNY.
However, you are advised to set a time and meet with your team to complete the tasks for mid-v1.0 and start working towards completing the first draft of the user guide.

Suggested exercises

The following exercises allow you to get used to larger codebase of Addressbook-Level2 and Addressbook-Level3 while at the same time introducing you to various OOP fundamentals.
- You may feel intimidated by the number of exercises. However, please note that it is not mandatory to do all of these exercises.
- If you are comfortable with the topic you can skip the exercise.
- You won't be graded for these exercises, but your tutors will provide feedback on your submissions.
Please submit clean pull-requests to the respective upstream repositories (take care to submit PRs to nusCS2113-AY1819S2/addressbook-levelX and not the se-edu upstream repo) before the tutorial.
During the tutorial, show to your tutor the evidence of learning the topic(s) and participate in relevant discussions.

OOP Basics

For the following exercises:

Submission: Create a PR against Addressbook-Level2. Try to make a clean PR (i.e. free of unrelated code modifications).

Remember to use team ID (e.g. M11-2) in your PR title.

[W2.6c] Implement a class

Note: In the above heading [W2.6c] is the id of the exercise to be used in the PR title (applicable to all exercises)

Relevant exercise in Addressbook-Level2: [Implement a class]

[W2.6e] Encapsulation

Relevant exercise in Addressbook-Level2: [Encapsulation]

[W2.6h] Class level members

Relevant exercise in Addressbook-Level2: [Class-level members]

[W3.1d] Inheritance

Relevant exercise in Addressbook-Level2: [Inheritance - for code reuse]

OOP Intermediate

For the following exercises:

Submission: Create a PR against Addressbook-Level3. Try to make a clean PR (i.e. free of unrelated code modifications).

Remember to use team ID (e.g. M11-2) in your PR title.

[W4.1c] Polymorphism

Relevant exercise in Addressbook-Level3: [Using Polymorphism]

[W4.1d] Abstract class/method

Relevant exercise in Addressbook-Level3: [Abstract classes/methods]

[W41.g] Interfaces

Relevant exercise in Addressbook-Level3: [Interfaces]

Requirements analysis

For the following exercises:

Submission: Create a PR against Addressbook-Level3. Try to make a clean PR (i.e. free of unrelated code modifications).

Remember to use team ID (e.g. M11-2) in your PR title.

Note: If you have completed recording user stores, use cases and non-functional requirements for your project, it is not necessary to do the exercises below.

Show to your tutor relevant items from your project to get feedback.

[W4.2b] Non-functional requirements

Relevant exercise in Addressbook-Level3: [User cases]

[W4.4a] User stories

Relevant exercise in Addressbook-Level3: [User stories]

[W4.4d] Use cases

Relevant exercise in Addressbook-Level3: [User cases]

Admin Appendix B (Policies) → Policy on plagiarism

Policy on plagiarism

We encourage sharing, but you should share with everyone in the class, not just a selected group. That is,

You are not allowed to share individual assignments with classmates directly.
You are not allowed to share project-related things with other teams directly.

You can even reuse each other's work subject to the 'reuse policy' given below.

If you submit code (or adopt ideas) taken from elsewhere, you need to comply with our reuse policy.

Detection:

Detecting plagiarism in code is quite easy. You are not fooling anyone by reordering code or renaming methods/variables.
As all your work is publicly visible on GitHub, sooner or later somebody will notice the plagiarism.

Penalties:

For submissions not affecting marks: We make a record of cases of plagiarism but we do not take further action. Such plagiarism does not disadvantage other students. Therefore, we prefer to spend all available resources on helping honest students to do better rather than to chase after dishonest students. If you think you gain something by plagiarizing, go ahead and do it. It's your choice and it's your loss.
For the final project/exam: Any case of claiming others' work as yours will be reported to the university for disciplinary action.

Admin Appendix B (Policies) → Policy on reuse

Policy on reuse

Reuse is encouraged. However, note that reuse has its own costs (such as the learning curve, additional complexity, usage restrictions, and unknown bugs). Furthermore, you will not be given credit for work done by others. Rather, you will be given credit for using work done by others.

You are allowed to reuse work from your classmates, subject to following conditions:
- The work has been published by us or the authors.
- You clearly give credit to the original author(s).
You are allowed to reuse work from external sources, subject to following conditions:
- The work comes from a source of 'good standing' (such as an established open source project). This means you cannot reuse code written by an outside 'friend'.
- You clearly give credit to the original author. Acknowledge use of third party resources clearly e.g. in the welcome message, splash screen (if any) or under the 'about' menu. If you are open about reuse, you are less likely to get into trouble if you unintentionally reused something copyrighted.
- You do not violate the license under which the work has been released. Please do not use 3rd-party images/audio in your software unless they have been specifically released to be used freely. Just because you found it in the Internet does not mean it is free for reuse.
- Always get permission from us before you reuse third-party libraries. Please post your 'request to use 3rd party library' in our forum. That way, the whole class get to see what libraries are being used by others.
- This also ensures you learn the ethics to attribute credits to the correct stake holders/owners.

Giving credit for reused work

Given below are how to give credit for things you reuse from elsewhere. These requirements are specific to this module i.e., not applicable outside the module (outside the module you should follow the rules specified by your employer and the license of the reused work)

If you used a third party library:

Mention in the README.adoc (under the Acknowledgements section)
mention in the Project Portfolio Page if the library has a significant relevance to the features you implemented

If you reused code snippets found on the Internet e.g. from StackOverflow answers or
referred code in another software or
referred project code by current/past student:

If you read the code to understand the approach and implemented it yourself, mention it as a comment
Example:

//Solution below adapted from https://stackoverflow.com/a/16252290
{Your implmentation of the reused solution here ...}

If you copy-pasted a non-trivial code block (possibly with minor modifications renaming, layout changes, changes to comments, etc.), also mark the code block as reused code (using @@author tags)
Format:

//@@author {yourGithubUsername}-reused
//{Info about the source...}

{Reused code (possibly with minor modifications) here ...}

//@@author

Example of reusing a code snippet (with minor modifications):

persons = getList()
//@@author johndoe-reused
//Reused from https://stackoverflow.com/a/34646172 with minor modifications
Collections.sort(persons, new Comparator<CustomData>() {
    @Override
    public int compare(CustomData lhs, CustomData rhs) {
        return lhs.customInt > rhs.customInt ? -1 : (lhs.customInt < rhs.customInt) ? 1 : 0;
    }
});
//@@author
return persons;

Adding `@@author` tags indicate authorship

Mark your code with a //@@author {yourGithubUsername}. Note the double @.
The //@@author tag should indicates the beginning of the code you wrote. The code up to the next //@@author tag or the end of the file (whichever comes first) will be considered as was written by that author. Here is a sample code file:
```
//@@author johndoe
method 1 ...
method 2 ...
//@@author sarahkhoo
method 3 ...
//@@author johndoe
method 4 ...
```
If you don't know who wrote the code segment below yours, you may put an empty //@@author (i.e. no GitHub username) to indicate the end of the code segment you wrote. The author of code below yours can add the GitHub username to the empty tag later. Here is a sample code with an empty author tag:
```
method 0 ...
//@@author johndoe
method 1 ...
method 2 ...
//@@author
method 3 ...
method 4 ...
```
The author tag syntax varies based on file type e.g. for java, css, fxml. Use the corresponding comment syntax for non-Java files.
Here is an example code from an xml/fxml file.
```

<textbox>
  <label>...</label>
  <input>...</input>
</textbox>
...
```

Do not put the //@@author inside java header comments.
👎

/**
  * Returns true if ...
  * @@author johndoe
  */

👍

//@@author johndoe
/**
  * Returns true if ...
  */

What to and what not to annotate

Annotate both functional and test code There is no need to annotate documentation files.
Annotate only significant size code blocks that can be reviewed on its own e.g., a class, a sequence of methods, a method.
Claiming credit for code blocks smaller than a method is discouraged but allowed. If you do, do it sparingly and only claim meaningful blocks of code such as a block of statements, a loop, or an if-else statement.
- If an enhancement required you to do tiny changes in many places, there is no need to annotate all those tiny changes; you can describe those changes in the Project Portfolio page instead.
- If a code block was touched by more than one person, either let the person who wrote most of it (e.g. more than 80%) take credit for the entire block, or leave it as 'unclaimed' (i.e., no author tags).
- Related to the above point, if you claim a code block as your own, more than 80% of the code in that block should have been written by yourself. For example, no more than 20% of it can be code you reused from somewhere.
- 💡 GitHub has a blame feature and a history feature that can help you determine who wrote a piece of code.
Do not try to boost the quantity of your contribution using unethical means such as duplicating the same code in multiple places. In particular, do not copy-paste test cases to create redundant tests. Even repetitive code blocks within test methods should be extracted out as utility methods to reduce code duplication. Individual members are responsible for making sure code attributed to them are correct. If you notice a team member claiming credit for code that he/she did not write or use other questionable tactics, you can email us (after the final submission) to let us know.
If you wrote a significant amount of code that was not used in the final product,
- Create a folder called {project root}/unused
- Move unused files (or copies of files containing unused code) to that folder
- use //@@author {yourGithubUsername}-unused to mark unused code in those files (note the suffix unused) e.g.
```
//@@author johndoe-unused
method 1 ...
method 2 ...
```
Please put a comment in the code to explain why it was not used.
If you reused code from elsewhere, mark such code as //@@author {yourGithubUsername}-reused (note the suffix reused) e.g.
```
//@@author johndoe-reused
method 1 ...
method 2 ...
```
You can use empty @@author tags to mark code as not yours when RepoSense attribute the to you incorrectly.
- Code generated by the IDE/framework, should not be annotated as your own.
- Code you modified in minor ways e.g. adding a parameter. These should not be claimed as yours but you can mention these additional contributions in the Project Portfolio page if you want to claim credit for them.

At the end of the project each student is required to submit a Project Portfolio Page.

Objective:
- For you to use (e.g. in your resume) as a well-documented data point of your SE experience
- For us to use as a data point to evaluate your,
  - contributions to the project
  - your documentation skills
Sections to include:
- Overview: A short overview of your product to provide some context to the reader.
- Summary of Contributions:
  - Code contributed: Give a link to your code on Project Code Dashboard, which should be https://nuscs2113-ay1819s2.github.io/dashboard-beta/#=undefined&search=github_username_in_lower_case (replace github_username_in_lower_case with your actual username in lower case e.g., johndoe). This link is also available in the Project List Page -- linked to the icon under your photo.
  - Features implemented: A summary of the features you implemented. If you implemented multiple features, you are recommended to indicate which one is the biggest feature.
  - Other contributions:
    - Contributions to project management e.g., setting up project tools, managing releases, managing issue tracker etc.
    - Evidence of helping others e.g. responses you posted in our forum, bugs you reported in other team's products,
    - Evidence of technical leadership e.g. sharing useful information in the forum
- Relevant descriptions/terms/conventions: Include all relevant details necessary to understand the document, e.g., conventions, symbols or labels introduced by you, even if it was not introduced by you.
- Contributions to the User Guide: Reproduce the parts in the User Guide that you wrote. This can include features you implemented as well as features you propose to implement.
  The purpose of allowing you to include proposed features is to provide you more flexibility to show your documentation skills. e.g. you can bring in a proposed feature just to give you an opportunity to use a UML diagram type not used by the actual features.
- Contributions to the Developer Guide: Reproduce the parts in the Developer Guide that you wrote. Ensure there is enough content to evaluate your technical documentation skills and UML modelling skills. You can include descriptions of your design/implementations, possible alternatives, pros and cons of alternatives, etc.
- If you plan to use the PPP in your Resume, you can also include your SE work outside of the module (will not be graded)
Format:
- File name: docs/team/githbub_username_in_lower_case.adoc e.g., docs/team/johndoe.adoc
- Follow the example in the AddressBook-Level4
- 💡 You can use the Asciidoc's include feature to include sections from the developer guide or the user guide in your PPP. Follow the example in the sample.
- It is assumed that all contents in the PPP were written primarily by you. If any section is written by someone else e.g. someone else wrote described the feature in the User Guide but you implemented the feature, clearly state that the section was written by someone else (e.g. Start of Extract [from: User Guide] written by Jane Doe). Reason: Your writing skills will be evaluated based on the PPP

Page limit:

Content	Limit
Overview + Summary of contributions	0.5-1 (soft limit)
Contributions to the User Guide	1-3 (soft limit)
Contributions to the Developer Guide	3-6 (soft limit)
Total	5-10 (strict)

The page limits given above are after converting to PDF format. The actual amount of content you require is actually less than what these numbers suggest because the HTML → PDF conversion adds a lot of spacing around content.
Reason for page limit: These submissions are peer-graded (in the PE) which needs to be done in a limited time span.
If you have more content than the limit given above, you can give a representative samples of UG and DG that showcase your documentation skills. Those samples should be understandable on their own. For the parts left-out, you can give an abbreviated version and refer the reader to the full UG/DG for more details.
It's similar to giving extra details as appendices; the reader will look at the UG/DG if the PPP is not enough to make a judgment. For example, when judging documentation quality, if the part in the PPP is not well-written, there is no point reading the rest in the main UG/DG. That's why you need to put the most representative part of your writings in the PPP and still give an abbreviated version of the rest in the PPP itself. Even when judging the quantity of work, the reader should be able to get a good sense of the quantity by combining what is quoted in the PPP and your abbreviated description of the missing part. There is no guarantee that the evaluator will read the full document.

Admin Appendix B (Policies) → Policy on help from outsiders

Policy on help from outsiders

In general, you are not allowed to involve outsiders in your project except your team members and the teaching team. However, It is OK to give your product to others for the purpose of getting voluntary user feedback. It is also OK to learn from others as long as they don't do your project work themselves.

Admin Exams

There is no midterm.

The final exam has two parts:

Part 1: MCQ questions (30 minutes, 25 marks)
Part 2: Essay questions (1 hour 30 min, 30 marks)

Both papers will be given to you at the start but you need to answer Part 1 first (i.e. MCQ paper). It will be collected 1 hour after the exam start time (even if arrived late for the exam). You are free to start part 2 early if you finish Part 1 early.

Final Exam: Part 1 (MCQ)

Each MCQ question gives you a statement to evaluate.

An example statement

Testing is a Q&A activity

Unless stated otherwise, the meaning of answer options are
A: Agree. If the question has multiple statements, agree with all of them.
B: Disagree. If the question has multiple statements, disagree with at least one of them
C, D, E: Not used

The exam paper has 50 questions. All questions carry equal marks.

The weightage of the Part 1 of the final exam is 25 marks out of the total score of 100.

Note that you have slightly more than ½ minute for each question, which means you need to go through the questions fairly quickly.

Given the fast pace required by the paper, to be fair to all students, you will not be allowed to clarify doubts about questions (in Part 1) by talking to invigilators.

If a question is not clear, you can circle the question number in the question paper and write your doubt in the question paper, near that question.
If your doubt is justified (e.g. there is a typo in the question) or if many students found the question to be unclear, the examiner may decide to omit that question from grading.

Questions in Part 1 are confidential. You are not allowed to reveal Part 1 content to anyone after the exam. All pages of the assessment paper are to be returned at the end of the exam.

You will be given OCR forms (i.e., bubble sheets) to indicate your answers for Part 1. As each OCR form can accommodate only 50 answers, you will be given 2 OCR forms. Indicate your student number in both OCR forms.

Some questions will use underlines or highlighting to draw your attention to a specific part of the question. That is because those parts are highly relevant to the answer and we don’t want you to miss the relevance of that part.

Consider the statement below:

Technique ABC can be used to generate more test cases.

The word can is underlined because the decision you need to make is whether the ABC can or cannot be used to generate more test cases; the decision is not whether ABC can be used to generate more or better test cases.

The exam paper is open-book: you may bring any printed or written materials to the exam in hard copy format. However, given the fast pace required by Part 1, you will not have time left to refer notes during that part of the exam.

💡 Mark the OCR form as you go, rather than planning to transfer your answers to the OCR form near the end. Reason: Given there are 100 questions, it will be hard to estimate how much time you need to mass-transfer all answers to OCR forms.

💡 Write the answer in the exam paper as well when marking it in the OCR form. Reason: It will reduce the chance of missing a question. Furthermore, in case you missed a question, it will help you correct the OCR form quickly.

💡 We have tried to avoid deliberately misleading/tricky questions. If a question seems to take a very long time to figure out, you are probably over-thinking it.

You will be given a practice exam paper to familiarize yourself with this slightly unusual exam format.

Final Exam: Part 2 (Essay)

Unlike in part 1, you can ask invigilators for clarifications if you found a question to be unclear in part 2.

Yes, you may use pencils when answering part 2.

The weightage of the Part 2 of the final exam is 15 marks out of the total score of 100.

Resources

Past exam papers will be uploaded on IVLE.

Admin Appendix C (FAQs) → What if I don’t carry around a laptop?

What if I don’t carry around a laptop?

If you do not have a laptop or prefer not to bring the laptop, it is up to you to show your work to the tutor in some way (e.g. by connecting to your home PC remotely), without requiring extra time/effort from the tutor or team members.

Reason: As you enjoy the benefits of not bring the laptop; you (not others) should bear the cost too.

Admin Appendix B (Policies) → Policy on publishing submissions

Policy on publishing submissions

The source code are publicly available and are available for reuse by others without any restrictions.
Is publishing submissions unfair to the team? We don't think so. If you were the first to think of something your peers are willing to adopt later, that means you are already ahead of them and they are unlikely to earn more marks by adopting your ideas.

Week 4 [Feb 4]

Overloading

Automated Testing of CLI Apps

Constants

Non-Functional Requirements

Non-Functional Requirements

Project Milestone: mid-v1.0

Brainstorming

Introduction

Organization setup

Repo setup

Issue tracker setup

Project Schedule Tracking

Using Issues:

Using Milestones:

Introduction

Non-Functional Requirements

What

Product Surveys

Suggested exercises

OOP Basics

[W2.6c] Implement a class

[W2.6e] Encapsulation

[W2.6h] Class level members

[W3.1d] Inheritance

OOP Intermediate

[W4.1c] Polymorphism

[W4.1d] Abstract class/method

[W41.g] Interfaces

Requirements analysis

[W4.2b] Non-functional requirements

[W4.4a] User stories

[W4.4d] Use cases

Policy on plagiarism

Policy on reuse

Giving credit for reused work

Adding @@author tags indicate authorship

What to and what not to annotate

Policy on help from outsiders

Final Exam: Part 1 (MCQ)

Final Exam: Part 2 (Essay)

Resources

What if I don’t carry around a laptop?

Policy on publishing submissions

Adding `@@author` tags indicate authorship