Way of Working

Use of GitHub

The goal of this course is to share as much knowledge as possible, as early as possible.

Therefore, for your work, you will get and use a dedicated GitHub repository within the delftswa2018 organization. This repository will be private to the organization, but visible to all students and teachers of the course. If your project is named XYZ, your team repository will be called team-XYZ.

Within your repository, different team members may work on different documents. In line with How GitHub uses GitHub to Build GitHub, use issues, clear commit messages, and pull requests to share and discuss your work.

Making good use of GitHub will be part of the grade.

Markdown

To simplify document sharing we will use GitHub flavored mark down for all documents.

Your markdown file should adhere to the DESOSA markdown style guide, which will help to integrate all deliverables and chapters into a single book.

We recommend that you generate a pdf from your markdown files using gitbook, without warnings. To that end, locally install gitbook-cli, and follow the instructions.

As an example on how to create a gitbook configuration for your deliverables and chapter, consider the DESOSA 2017 git repository, and in particular the SUMMARY.md file which yields the content of the book. The pdf can then be created with

$ gitbook pdf . desosa2017.pdf

Mattermost

Besides communication via GitHub issues, pull requests, and comments, we will use a dedicated Mattermost group for communication.

Project Journal

You will have considerable freedom in this course. Nevertheless, a steady heartbeat is required, and you are accountable for how you spend your time.

An architect is always eager to learn more. In this course, you have 5 EC available for software architecture in 8 weeks, giving a minimum effort of 5 * 28 / 8 = 17.5 hours per week that you should spend on this course.

Grading will be also based on the progress you made compared to your initial knowledge and skill level, not just based on a preset end-goal.

To make this possible, it is important that you and your team provide insight in what you do each week. To that end:

  1. Create a file journal.md in the root of your project repository
  2. For each week, write a couple of paragraphs what you did as a team

  3. Maintain a spreadsheet (see hours.xlsx for the format and example entries) keeping track of the hours each team member spent and on which tasks.

    Note that maintaining binary files in git is cumbersome, so it is probably easiest to maintain a google docs spreadsheet somewhere.

    When handing in a sub-deliverable, you must also hand in your hours: see below.

Your journal and hour declarations will be taken into account when grading each of the sub-assignments, as well as when grading the final book chapter.

Filling in correct hours is a group responsibility. All team members must agree on the hours any team member indicates that he or she has spent.

Handing in via a GitHub release.

For handing in the results, we’ll use GitHub releases which are based on git tags.

As tag names, use D1, D2, etc in your team-XYZ repository for the deliverables. Optionally, you can add additional info in the tag name, like D1-stakeholders.

As always, your work should be reviewed and merged via pull requests, and this holds in particular for (the final version of) the (sub)-deliverables.

The tag should be on a commit that has been merged into master via a pull request. The timestamp of that commit (i.e., the time when the ‘merged’-email is sent by GitHub) counts as the moment you handed in the work.

With your release, you should upload a pdf file containing up to date hour declarations for all team members.

Grading will only start after the deadline. Therefore, as long as the deadline has not passed, you can always update your work, provided it is clear what the final tag name is.