IN4315: Software Architecture

Assignment 2021

Table of Contents

Getting Started

To get started with the assignment, the following tasks need to be completed:

  1. Form a team and register on Brightspace
  2. Pick a suitable project and claim it on the Brightspace forum
  3. Write your project introduction and make your first contribution to DESOSA on GitLab

Team Formation

As software architecture is all about collaboration and communication, the work must be done in teams:

  1. Required team size is 4
  2. Aim for diversity in your team. For example, aim at at a mixture of master tracks, backgrounds, expertise, cultures, countries, etc.
  3. Form your group in Brightspace. Go to Collaboration -> Groups.

If you are looking for partners, you can post a message on our Brightspace forum (there is a topic for partners wanted), and offer your expertise.

Picking a Project

In principle you are free to pick any open source project on GitHub. Take the following factors into account:

An active project should have 1 or more pull requests per day. To get you started, we hand-picked a list of projects which are large, actively developed, maintained by a vibrant community, and are not analyzed in the previous runs of this course. You cannot reuse a project that studied by other students in 2019 or 2020: see the list of non-projects.

To claim a project: Post on the Brightspace forum, title Claiming project P, explain why you like this project in the issue, and indicate the 4 team members that will work on this project as well as your group number. Make sure to add their GitLab accounts in the issue so we can find them.

After your project choice is approved, you will be granted access to the GitLab repository where you can find your project in the ./content directory. Add a short (around 100 words) enthusiastic description of the project to the _index.md file in your project sub folder (see the usage instructions of the DESOSA project for more information). Consider adding a logo or some representative image, and provide all the required meta-data. Also fill out the author details with your names and a small introduction.

Getting Access to GitLab for Writing

All team members will get access to a shared GitLab repository hosting the sources of DESOSA 2021.

Within this repository, each team will have one dedicated project sub-folder to work in. Teams should only add changes to their own sub-folder (./content/projects/<projectname>).

The repo includes all essays written for all projects. The essays themselves are writen in Markdown, and rendered using Hugo. Usage instruction are provided on the README page of the DESOSA project.

Follow all good software development practices in this repository, such as using issues and milestones for planning, merge requests, review, etc. Show that you are well-organized, and that the teachers can clearly see what you did and what you are planning to do.

You are encouraged to use issues and must use merge requests, properly labeling them with an identifier for your project.

(Some teams prefer to use a collaborative tool like Overleaf or Google Doc for “pair writing”. That is OK, as long as the eventual result is committed, in time, in the gitlab repository in proper markdown format.)

The Assignment

The main part of the assignment consists of three parts:

  1. Writing four essays about different aspects of your project and reviewing the essays of others teams
  2. Contributing to your project
  3. Keeping track of your progress through personal journals

Essays

Strong writing skills are an invaluable asset for an architect. To quote Dan Heller in his “Ten Principles for Growth as an Engineer”:

Crisp technical writing eases collaboration and greatly improves your ability to persuade, inform, and teach.

Therefore, we will use this course to train and improve our writing skills.

Each team will write four essays. Each essay should be around 1500-2000 words. After 2000 words teachers (or any reader, in fact), reserve the right to stop reading, which may affect your grade. We’ll be counting words by running Markdown Word Count, developed by a former Software Architecture student, on your .md markdown files.

Your essays will be evaluated based on the following:

  1. The text is well-structured, with a clear goal, a natural breakdown in sections, and a compelling conclusion.
  2. Sentences, paragraphs, and sections are coherent. They naturally build upon each other and work towards a clear message.
  3. The arguments laid out are technically sound, and of adequate technical depth.
  4. The English writing is grammatically correct
  5. The text clearly references any sources it builds upon
  6. The essay is unique and recognizable in its voice and its way of approaching the topic
  7. The essay is independently readable
  8. The story-line is illustrated with meaningful and appealing images and infographics.

The intended audience for the essays consists of computer science students or software engineers, interested in learning about architectural aspects of your open source project.

A publicly visible blog is available through which teams can publish their essays. We are publishing the essays throughout the course (and not just all at once after the course). We will use the blog to engage with and share our work with the open source community. Published essays (blog posts) will carry a CC BY-SA 4.0 license, allowing the open source projects to include the resulting posts in their own documentation. You can decide yourself which posts you want to make public by means of simple meta-data flag in your Hugo markdown document.

Essay 1: Product Vision and Problem Analysis

The starting point for your architectural analysis is a description of the vision underlying your project and its future success. Aspects to take into account include:

  1. A concise, inspirational characterization of what the project aims to achieve
  2. A brief explanation of the key domain concepts (underlying domain model)
  3. A description of the system’s main capabilities (e.g. use cases), as they are visible to the typical (end) user
  4. A description of the current and future (external) context in which the system operates
  5. An analysis of the stakeholders involved in the project, and what they need from the system so that it is beneficial to them
  6. A characterization of key quality attributes the system must meet
  7. A product roadmap, laying out the main directions anticipated for the upcoming years
  8. Ethical considerations of the system and its construction process

It may be the case that some of these aspects do not naturally match your open source system under investigation. In that case, say so explicitly, and explain why you think this is the case in your essay. Instead offer a deeper analysis of other relevant aspects.

Relevant literature for this essay includes

Essay 2: From Vision to Architecture

While the first essay focuses on the set of fundamental concepts or properties of the system in its environment, in the second you explore how these are realized through the system’s architectural elements and relationships, and the principles of its design and evolution. Aspects to take into account include:

  1. The main architectural style or patterns applied (if relevant), such as layering or model-view-controller architectures.
  2. Containers view: The main execution environments, if applicable, as used to deploy the system.
  3. Components view: Structural decomposition into components with explicit interfaces, and their inter-dependencies
  4. Connectors view: Main types of connectors used between components / containers.
  5. Development view, covering the system decomposition and the main modules and their dependencies, as embodied in the source code.
  6. Run time view, indicating how components interact at run time to realize key scenarios, including typical run time dependencies
  7. How the architecture realizes key quality attributes, and how potential trade-offs between them have been resolved.
  8. API design principles applied

It may be the case that some of these aspects do not naturally match your open source system under investigation. In that case, say so explicitly, and explain why you think this is the case in your essay. Instead offer a deeper analysis of other relevant aspects.

Relevant literature for this essay includes

Essay 3: Quality and Evolution

With key aspects of the architecture described, the third essay focuses on means to safeguard the quality and architectural integrity of the underlying system, with special empahsis on the rate of change. Aspects to take into account include:

  1. The overall software quality processes that apply to your system
  2. The key elements of the system’s continuous integration processes
  3. The rigor of the test processes and the role of test coverage
  4. Hotspot components from the past (previously changed a lot) and the future (needed for roadmap)
  5. The code quality, with a focus on hotspot components
  6. The quality culture, as evidenced in actual discussions and tests taking place in architecturally significant feature and pull requests (identify and analyze at least 10 such issues and 10 such pull requests)
  7. An assessment of technical debt present in the system.

Again, it may be the case that some of these aspects do not naturally match your open source system under investigation. Also, doing all of these well may not fit in a single essay. Select those aspects that are most relevant, and do a thorough analysis for them.

If you conduct measurements, you may find that certain numbers point at poor code quality. In such cases, offer an explanation why the code ended up like it is now, assess whether trade-offs have been made, and demonstrate leadership by offering constructive proposals how to resolve the problems you found.

Relevant pointers for this essay include:

Essay 4: Deepening your Analysis

Your team’s final essay serves to deepen your analyis, and can be on one of the following topics.

Essay 4.VAR: Variability Analysis

An analysis of the variability modeling, management and implementation mechanisms that are relevant to your system, based on the lecture by Xavier Devroey. The details of this essay are described separately.

Essay 4.SUS: Sustainability Analysis

Look into the change history of the project and find code changes that are related to green computing, based on the Green Software Engineering lecture by Luís Cruz. Present and discuss the rationale behind those changes:

When discussing energy efficiency, critical thinking is key. Aspects to cover include:

Essay 4.DIS: Distribution Analysis

An analysis of the distribution architecture and design choices of your system, based on the lecture by Burcu Kulahcioglu Ozkan.

You are suggested to address the following questions in your essay:

While analyzing trade-offs, you can discuss the availability, consistency, and partition-tolerance properties of the system:

Essay 4.AMD: ARCHITECTURE.md

Recently, Aleksey Kladov suggested that projects of 10K-200K lines of code should have an ARCHITECTURE.md file. If you believe this would be important for your project as well, do as follows:

Note that interaction with the project is key for this assignment, since otherwise the most likely outcome is that your proposal for an architecture.md file is rejected or ignored.

Essay 4.OTH: Topic of choice

A topic of choice, specific to your project. This can be based on

If you pick this option, consult the teachers first with a short proposal (a few sentences) explaining what you’d like to investigate, and how this is relevant to your project.

Submissions

Once you are ready to submit your essay, please follow the following steps:

  1. Open a merge request on GitLab, and make sure that your team members review your changes. If everything looks good and everyone approves, you can merge your MR.

    Important note: Your MR needs to be merged for it to be considered submitted.

  2. To prepare your essay for peer reviews, a PDF, containing only your new essay, needs to be created. See the README on GitLab for instructions on generating such a PDF locally or on the DESOSA site.

  3. Submit your essay to peer.tudelft.nl, the peer evaluation system that we use. After logging in with your NetID, you can find the Software Architecture course under “Enrolled Courses”. On the course page, select the assignment matching your essay and submit the PDF from step 2.

    Note: This only needs to be done once per team.

System Contributions

To familiarize yourself with the system under analysis, your team will contribute to the system. This will take the form of a pull request to the system. Aspects to consider include:

  1. It is probably a good idea to start with a very simple pull request, just to understand the whole process.
  2. Starting with a documentation pull request might be a good way to get started.
  3. Many projects have labels for issues that are easy to start with for newcomers to the project. Explore these and see if you can help.
  4. After one or two simple pull requests, try to contribute more substantially, for example in refactorings or simple features.
  5. In your interactions (in GitHub comments) with the developers who are responsible for integrating your change, be polite, to the point, and responsive.
  6. Follow any guidelines, for example in the projects CONTRIBUTING.md file.

For pull requests you’ve actually submitted, create a new contributions entry in the DESOSA project to share your contributions on the website and PDF/epub.

There will be two deadlines, for two simple reports:

The two reports can be put in a file contributions.md, which you can put in your journals folder (so that it is ignored by Hugo). As an indication, around 100 words will probably suffice per planned (or terminated) pull request.

Pull requests will be graded, based on the following criteria:

While your aim is of course that the pull request gets merged, the merge itself is not part of the grade.

Individual Journals

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

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.

Use this time to learn as much as you can, as an architect is always eager to learn more. Grading will also be 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 journal file for each team member in the journals directory of your project.
  2. Team members individually reports their own weekly experiences and effort in the course. It is important to commit and push these reports weekly (or even more frequently), and that you commit your own updates.

In the journal, you can offer a story of what you learned, what activities you participated in (lectures, meetings). All effort related to the course can be included, including routes taken that do not directly lead to text in your essays (e.g., projects considered when selecting your project). For each week, also include the number of hours you spent that week on the software architecture course.

Final Presentation

Video

The course will be concluded with an online presentation day. To that end each team prepares a 10 minute video highlighting their work.

The primary audience for this video is your fellow students who also followed this course. Furthermore, try to make the video of interest to current or future contributors of the open source system you analyzed.

Aspects you can cover in your video include the purpose of the system (essay 1), the underlying architecture (essay 2), the quality assurance process (essay 3), as well as your choice of topic for essay 4. As it is impossible to cover everything you did, please focus on what sets your system apart from many other systems – the key thing other students in this course should learn about your system.

In terms of video style, feel free to use your full creativity. The best videos trigger applause and awe when presented to all students. If possible, try to make it clear that the video is team work, by letting all team members feature in the video.

You should upload your video as a (unlisted or public) YouTube video, and add the URL to your project page on the DESOSA website. See the DESOSA README for full instructions on how to add the video. You can indicate whether you want your video to be public. Both should be done before the deadline of the presentation video.

Presentation Day

During presentation day, we will create six sessions of approximately two hours. Sessions will start at 10:00, 12:30, and 15:00, in two parallel tracks (in two separate Zoom calls).

For each team, there will be 20 minutes. During the first 10 minutes the team’s video will be shown. During the second 10 minutes there will be Q&A. All four team members must be present, and should be involved in answering questions.

Each team is expected to join the full (two hour) session during which their own video is shown and discussed, and participate actively in the discussions of the other four teams in the same session.

Furthermore, individual students are welcome to join any other session and participate in the Q&A (but this is not compulsory).

Grading

Students should fill in a form for each of the four presentations and Q&A sessions they participate in. This form will distinguish content depth, presentation style, and the handling of questions.

In each session 1-2 teachers will participate, who will also grade the teams.

The Q&A sessions including the chat will be recorded.

References

  1. Cesare Pautasso. Software Architecture: Visual Lecture Notes. Leanpub, 2020. leanpub.com. ↩ ↩2

  2. Peter Hruschka and Gernot Starke. arc42: Effective, lean and pragmatic architecture documentation and communication. https://docs.arc42.org/home/ ↩ ↩2 ↩3

  3. Jim Coplien Gertrud Bjørnvig. Lean Architecture for Agile Software Development. Wiley, 2010. ↩

  4. The C4 model for visualising software architecture. https://c4model.com/. ↩