# iteration-02.plan.md
# SAM

## Iteration 1

* Start date: Friday November 1, 2019
* End date: Wednesday November 12, 2019

## Process

#### Roles & responsibilities

#### Skander Moalla _Aka Scrum lord_
**Roles:** Scrum master / reseach scientist
**Description**: As a scrum master, Skander is responsible of ensuring a truly agile development cycle by planning the sprints and making sure they are executed as planned: respect of sprint backlog and organization the necessary meetings.
As a scientist, he is responsible of developing and testing the main algorithm that will be used for the matching feature.
**Strengths:** 2 years of experience with python, solid maths training, game theory and mechanism design enthusiast, experienced in team leading.
**Weaknesses:** Never used Django nor React, lacking experience in architechture/stack design, unaware of deployment and shipping technologies.

#### Loan Tricot
**Roles:** Product owner / manager / architect
**Description:** As a product manager, Loan must point out which part of the developers’ work is useless to the client. He is the sanity check of the team. The product manager must be proactive and guide developers’ work by interacting often with the early adopter to receive feedback and further understand the customer’s needs.
As a tech architect, Loan is concerned with the separation of the application implementation into different components. He ensures each component adheres to a specification so that they can all rely on each other’s behavior and be developed independently.
**Strengths:** Significant experience with google cloud platform and architecting solutions. Excellent python programmer.
**Weaknesses:** Underestimates how much time a task will take. A strong sense of how things should be done — maybe too strong (clearly too strong).

**Development Team**
#### Teo Chaban
**Role:** Researcher and Developer
**Description**: Will be responsible to research the best algorithms to solve our problem, and try to taylor it to the particular needs of the project. Will also be responsible to make sure that the coding side of development is running smooth, and implement the researched algorithms.
**Strengths:** Backend coding, statistics, math, development methodologies.
**Weaknesses:** Limited experience with integration of back and front end and no experience with deployment technologies.

#### Marine Hoche
**Role:** Researcher
**Description** read scientific papers (mainly on matching algorithms) to find the best algorithms to solve our problem and present the solutions to the rest of the team, develop and test these algorithms
**Challenges** Find efficient algorithms that really suit our needs, discuss with the product manager to verify the compatibility with the consumer's needs and with the tech leader for the smooth integration of the algorithms.
**Strengths**: Strong background in maths and statistics, comfortable in coding in python, already worked on a software development project within a big team
**Weakenesses** methodologies (be too focused on the research side ie finding the best algorithm possible without testing intermediate options), code documentation, limited knowledge in version control

#### Guillaume Lainé
**Role(s):** Software Engineer
**Description**: Will be responsible of using the technology stack chosen by the tech lead and organising and developing the features thought up by the researchers on the team, and documenting code.
**Strengths:** Mathematics, coding, documentation.
**Weaknesses:** UI/UX, version control, development methodologies.

#### Osman Afandiyev
**Role:** Tech lead
**Description:** Will be responsible for choosing technologies which are most optimal for development and deployment of a project and maintaining overall awareness of those technologies usage in a team.
**Strengths:** Have previous experience with full stack development, knowledge of various technologies out there, rich experience with development of database.
**Weaknesses:** Limited knowledge of developing algorithms and proving it's correctness, no knowlege/experience of graphic design or any front end.

#### Grey Lee
**Role(s):** Designer
**Description**: Will be responsible for SAM's UI/UX and visual design, including logos and style guide. Will also be responsible for integrating design elements in front end development.
**Strengths:** Graphic design, front end, client communication
**Weaknesses:** Limited experience with the tech stack platforms, algorithm design, back end.

#### Team Rules

##### Culture

At SAM the hapiness and productivity of each team member are priorities. It is important that everyone has the opportunity to develop the skills they value. In fact, working on a task that deeply interests a member and serves their personal and academic objectives is much more enriching. It will be performed efficiently, carefully and with greater precision. We have thus insisted on this point during the role assignment, we didn't require someone in charge of a particular topic to be particularly skilled in it but rather to be strongly motivated to learn it.

Diversity is what makes our team strong. That is, diversity in academic background but also diversity in origin, personality, and values.

##### Communication

###### Within the team
We use slack to communicate. This platform allows us to set different channels, thus having subteam communications and more general ones on the same platform, along with a channel to communicate with our assigned TA.

We have an urgent channel on Slack which must be checked at least once a day. All the members must have notifications enabled on their phone for this specific channel.

###### With our partner:
We have an independent project but have an early adopter which is Ecole Polytechnique in France. We are directly communicating with Sophie — Who manages the study abroad commitee — by email and video conference.

##### Meetings:
* We meet twice a week: Once during the tutorial slot on Tuesdays and once on Friday from 1pm to 3pm in Robarts or Gerstein.
* Weekly meetings are mandatory. It is possible to change the date/time of the meeting in case someone is unavailable.
* If an additional meeting is needed or a meeting must be rescheduled, it should be planned at least 2 days beforehand.
* The scrum master is responsible for the meeting's schedule: the scrum master
* Books the venue and seds reminders to the team
* Plans the subjects that will be addressed in the meeting
* Ensures every item is addressed in a timely manner
* Brings candies to the meeting

##### Conflict Resolution:
###### Conflict scenarios:

* _A key decision has to be taken but there are two different points of view within the team:_
It's necessary to talk about it, to list the pros and cons of each idea, that every member of the team tells the other his/her point of view on each idea and after that to do a vote. In this way, we can come up with the solution that is the best for the team and the projects and every member will have deeply thought about the consequences/interests/defaults of each of the different options.

* _We are one hour before the deadline of one of the deliverable and one of the team member has not completed his/her task:_
To prevent this situation, we will do a meeting a couple of days before each due date to review the work of everybody and give time for some modifications. If this still happens, then if it was due to a personal issue, the team will show its best support to the member and will explain the circumstences to the teaching team hoping to get an extension of the deadline. If the team member failed to complete their task because of bad time management, then we will submit the assignment as it is, bear the responsibilty together. But the team member will have to bring tasty snacks to the next meeting.

* _Two team members do not get along and are thus unable to work on a common task (inefficiency in their work because of recurrent conflicts)._
The scrum master, or any other team member will evaluate the conflict, make their best to solve them: if it is due to miscommunication or values. In any way, the team will never tolerate any kind of conflict to perdure. However for special circumstances. These two persons would be assigned independent tasks.

#### Events

We meet twice a week. Once during the tutorial slot on Tuesdays and once on Friday in Robarts or Gerstein.
We try to perform our stand up meetings at the beginning of those meetings, however the scrum board on github serves as a replacement for standup meetings.
Friday's meeting, the longer one, is also the one during which we schedule our sprint planning, review, and retrospective. Since we value everybody learning from the project, we also discuss important decisions and challenges of each subteam during these meetings. Most importantly since we do not see each other everyday, it is crucial for our friendship and team spirit to see each other at least twice a week.

Code reviews are done online.

##### Previous team meetings: (add meeting minutes)
* 04/10/2019 - Gerstein 2000 - Problem definition + Role distribution
* 11/10/2019 - Robarts Room 2 - Partner meeting review + Deliverable 1 review + Mockup design
* 18/10/2019 - Gerstein 2106 - Backlog refinement
* 25/10/2019 - Gerstein 2106 - Resource modeling
* 01/11/2019 - Gerstein 2107 - Backlog refinement + sprint planning

##### Future meetings:
* 08/11/2019 - Algorithm design + Front-end design review
* 12/11/2019 - Sprint review + Postmortem

#### Partner Meetings:
We do not have an official partner but we do have an early adopter: Ecole Polytechnique. As mentioned above. We are directly communicating with Sophie — Who manages the study abroad commitee — by email and video conference.

##### Previous partner meetings: (Add meeting minutes)
###### First meeting - October 10 - Zoom
The very first meeting with our early adopter was about understanding the customer’s problem better, and identifying where we can bring value:
- What is their current approach to matching students and exchange programs (Detailed process with explicit steps) ?
- How much time does each step take ? Which part of the process os the most frustrating ?
- Given our suggestion for a solution (a short presentation of our concept product), what do they believe will help them the most / which feature do they believe will have the more value ?
- Can they provide us will a small dataset for our proof of concept ?

###### Second meeting - 06/11/2019 - Zoom
Discussed the matching algorithm and important statistics to evaluate the efficiency of the algorithm.
##### Future partner meetings:
###### Review meeting - 13/11/2019 - Zoom

#### Artifacts

List/describe the artifacts you will produce in order to organize your team.

* Artifacts can be To-Do lists, Task boards, schedule(s), etc.
* We want to understand:
* How do you keep track of what needs to get done?
* How do you prioritize tasks?
* How do tasks get assigned to team members?

##### Github projects and issues:

After finding out that ZenHub was just a trial version. We made our own version of ZenHub out of GitHub projects, issues, and milestones. We defined custom artifacts that help us organize our workflow. Details can be found on the README file of the repo.
https://github.com/csc301-fall-2019/team-project-sam/tree/develop

##### Other tools:
- Meeting notes for every partner meeting [google doc link]
- Feature specifications using https://www.ietf.org/rfc/rfc2119.txt

Documents are stored on github or google drive depending on which of those is more appropriate.

#### Deployment and Github Workflow

We distinguish two types of branches:
- permanent branches
- ephemeral branches

##### Permanent branches

The former type of branch always have semantics associated to them. In addition, several rules must be respected when dealing with permanent branches:
1. all amendments to permanent branches MUST go through pull requests
2. all pull requests to permanent branches SHOULD be reviewed before being merged
3. the product owner is responsible for all merging of pull requests and MUST, before merging, either:
- review the pull request
- assign a relevant reviewer or discuss the pull request with a relevant member of the team

The most present permanent branch we use is the `develop` branch. The state of the develop branch _mostly_ represents a _working_ application. This rule is not too strict: in the interest of speed of development, we do not perform comprehensive reviews for all pull requests submitted to `develop`. Reviews of pull requests to `develop` are mostly important to ensure everyone is on the same page concerning the direction of the project.

Of course, another significant permanent branch is the `master` branch. The `master` branch's rules are more strict and must absolutely be respected:
1. all amendments to the `master` branch MUST go through pull request _from the `develop` branch_
2. all pull requests to the `master` branch MUST be reviewed by more than 2 team members, including the _product owner_ (Loan Tricot)
3. the state of the `master` branch MUST represent a _working_ application and this MUST be ensured through thorough testing
4. Each new state of the `master` branch SHOULD be tagged and represent a new release (version) of the application

By _working_ application we mean application which can be run on a developer's computer, or, when the context is stricter, on a production environment. In our case, this means Google App Engine.

Permanent branches are useful because they are the meeting point of all developers' work. A pemanent branch's state cannot be coherent unless developer closely collaborate to make it so. They force interaction and force developers to review (and therefore familiarize themselves with) each other's code.

Our current stage of development does not warrant the use of more _permanent_ branches than those mentioned above, however it is possible this will change in the future. We are in particular considering `hotfix` and `release` branches as described in [this blog post](https://nvie.com/posts/a-successful-git-branching-model/).

##### Ephemeral branches

The latter type of branches are the looser in terms of rules. Ephemeral branches are almost always associated to an issue. They follow a number of rules:
1. Ephemeral branches MUST be branched off `develop` or another ephemeral branch
2. When they are associated to an issue, they SHOULD be named after the ID of this issue (e.g. #11)
3. When the issue to which they are associated is resolved, they SHOULD be removed (and conversely)

Ephemeral branches are our primary tool of collaboration in the sense that, unless invited to, a developer of the team has no business working on an ephemeral branch created by another developer. Ephemeral branches represent responsibility boundaries. They are how the developers of the team avoid stepping on each others' toes (avoid conflict).

##### A look back to pull requests

Branches represent boundaries. They cannot therefore be expected to fully represent our collaboration process. At the heart of all interactions between the developers of our team are pull requests. Pull requests allow developers to:
- make their case concerning an architectural decision
- ask for input from teammates concerning an architectural decision
- review and familiarize themselves with teammates' code

One type of pull request we give particular attention to for the purpose of this document is those pull requests from an ephemeral branch to `develop`. Indeed, those pull requests are often associated to the end of the associated branch and therefore the closing of the associated issue. That is, reviews of this pull request de facto assess whether the issue can really be considered closed.

##### Deployment - when do we run it ?

We mentioned above that the state of the `master` branch should always represent a working application ; and we specified this working application should be runnable in a production environment. This production environment is Google App Engine. Because GAE is decoupled from the git workflow, we must define the version of the GAE environment to always be associated to the most recent `master` branch state. That is, cloning the `master` branch to a GAE environment should yield a working application at all times.

This is very useful from a product owner's perspective. The end product is a working application, and developers should _never_ lose sight of that. This rule of the master branch is a fundamental reminder.

## Product

#### Goals and tasks

Our goal for this first sprint is to deploy SAM with the enough
features desired by Sophie - the head of the exchange selection committee to prove to her that SAM can become her main tool to manage the study abroad program.

These features are described in the following two user stories.

* As a member of the student exchange selection committee selecting students for each university, I want to provide a ranking of applying students for each exchange university and obtain in return the best distribution of all students across these universities, in order to save myself the time of building numerous student-uni configurations and comparing them
* A feature allowing users to rank all students having applied to a university, for all available universities.
* A Match feature which matches each student to a university, respecting universities' quotas and students' relative rankings, while trying to maximize student satisfaction by giving each their best choice.

* As a student officer reviewing the selection outcomes, I want to be able to easily visualize the distribution of students with respect to their selected wish, in order to evaluate at a glance the general conciliation of student wishes to selection outcome.
* A feature which, following each matching process, displays a graph of the number of students as a function of the n-th choice obtained by each student.

The main tasks we will have to do are the following (in order of decreasing priority):
Our priority criteria though, is not the one we would have chosen if we were not rushed by the deadline. Indeed, we chose to priorize the tasks that will show on a deployed app (e.g. frontend) over features that only show quality after thorough research (e.g. Optimal matching algorithm).

* Frontend
* Login page
* Home page
* Matching criteria page
* Matching results page
* Matching history page
* Two matchings comparison page
* Individual student Data page
* All students overview page
* Add student page
* Edit student page
* University overview page
* Add university page
* Edit university page
* Resources and Database interfaces
* Write JSONSchema descriptors for each resource, most rigourous form of documentation.
* Write Django models to implement the resource storage system (database, implicitly).
* Write specific documentation on each resource’s methods using RFC 2119 keywords
* API
* Student Resource Implementation
* University Resource Implementation
* Region Resource Implementation
* Application Resource Implementation
* Matching parameters Resource Implementation
* Matching algorithms
* Gale-Shapely algorithm
* Unit-test Gale-Shapely
* Matching benchmark/statical overview
* Data extraction and testing of Sophie's exel
* Compute score of student in a wished university
* Rank students per university
* Comparison tool/Differences log - history of all previously saved matches and comparison of selected past matches

These tasks are further detailed and organized on our GitHub scrum board.

Here's a link to the draft of our backlog refinement file:

https://docs.google.com/document/d/11H8TjivacBM3umNkNFGm1WZ2gix7eVd4w4HtQhAdNp0/edit?usp=sharing

https://hackmd.io/@skandermoalla/Hyo6KyccH

#### Artifacts

Our first artifact is obivously the SAM webpage. It will hopefully include the pages mentioned in the previous section (i.e. Login, Home, Martching criteria and results).
It will also be functional: displays real data fetched from the SAM server, and compute matchings with the algorithms in the server.
This artifact will allow us to show the first functionalities of SAM to Sophie and have her feedback/validation.

Our second artifact is the mockup we designed for D1. This artifact allows us to iteracte quickly on the front-end design of SAM. Indeed, it is quick to edit, and can be shared with a simple link with Sophie. https://adobe.ly/2B262ZT

Our third artifact, which is the most important for us, will be a set of statistics showing the results of the algorithm used by SAM when used on last year's applications. Indeed Sophie has shared with us her work on last year's study abroad applications - including the resulting matchings - and we plan on using it as a mock to prove to Sophie that SAM can have a better outcome that manual matchings.