Course Project

The purpose of this document is to build a specification and framework for the work that you’ll be doing. Ultimately it is also a model against which your work can be assessed. Please read it thoroughly.

Instead of doing a large, unstructured project this semester, you’ll be contributing to an open source project. Specifically, we’ll be contributing to the Application Services team at Mozilla.

Their project is to build a cross-platform component that can be used in Firefox browsers and other mobile apps (like Lockwise).

Your first structured assignment will be to explore the team’s GitHub repo and read their documentation.

Before you do anything, read the Mozilla’s Community Participation Guidelines. By continuing to remain in the class, it is assumed that you have agreed to hold yourself to this standard in anything associated with this class (and so do I). As always, you can submit anonymous feedback and comments to me through my feedback form.

The Objectives

The objectives of this format are many-fold. This is a large, complex piece of software that is under active development.

• You gain experience onboarding yourself onto an existing project.
• You will see and experience the process and reality of real-world software engineering.
• You will gain experience with the process skills that are necessary for building real-world systems: deep debugging, integration challenges, testing and deployment, configuration management, etc.
• You will work with code a lot–reading it, writing it, refactoring it, etc.

The Work

Finding Work

First of all, the issues list is a source of issues to take up. The team has very graciously groomed quite a large set of good first issues for you to take up.

Part of your work will be finding work. There are lots of ways to do this.

However, you can also be creative! Explore the codebase. There’s lots of ways to find meaningful work to do:

• Remember that meaningful work isn’t always coding. Is there project documentation that can be improved? Did you have difficulty getting things to build on your platform? Improve the documentation! Anecdotally, the first task for engineers joining my team was for them to go through the “Noogler” docs for my team and update them.
• Is a file or component not well documented? Do you find the comments to be hard to read, or notice that there’s not many comments on something you think should be commented? Write or revise comments.
• Do you think that a function or component could be refactored to make it cleaner (i.e., following the principles in the books)? Refactor it.
• Does a component lack tests? Add them.
• Search the codebase for TODO, XXX, etc. Can any of these be resolved? Frequently a TODO gets added during review when minor but orthogonal improvements are suggested.
• Also look beyond the first issues. Take a look through the backlog issues and see if there’s anything that you might be interested in.
• Could there be better tooling/documentation for tooling (e.g., automated test coverage, scripts, etc.).
• Application Services is a library used by other apps. Could there be better/more demo apps that use it (so that potential integrators can see how to integrate with it)? Can the CLI app be improved?

Design

For nontrivial, nonjanitorial work you will likely need to do some design, even if it’s a one-page description of what you’re proposing. Create a Google doc to share and get comments/feedback on your design. Share it with your team, me, and any other relevant people.

Teams

You will be working with a team of students. You are expected to be making regular and meaningful contributions to your team’s goals. Your team should meet at least once a week outside of class, and, whenever possible, your work should be done pair programming. Regardless of your opinion of pair programming, it is effective, and there are very high profile accounts of its success.

Your team should be 4-5 students. That means there will be ~6 in the class.

Reporting

Beyond our weekly standup, your team should send a weekly report to me highlighting the accomplishments of the team and who on the team was responsible for these accomplishments (including percent contributions, if applicable). This report should also include your team’s activity, including any meetings that took place.

At the beginning of the semester, choose one team member to do status reporting. Your team must agree on the status report before submitting.

Use this form to submit your status report.

Roles

Note that I’m not assigning roles. In some software engineering university group projects, there’s a “product manager” (or “project manager”). There’s no point of that in this context.

It probably is a good idea for your team to organize itself around a leader, though, especially for large-ish collaborative tasks. That leader can be responsibility for work prioritization and assignment/re-assignment.

Context

In Software Development, SWEs frequently talk about having context with what they’re working on. Though this can mean a lot of things, it typically means having an understanding for what, where, and why work needs to be done and how complex that work is. When you’re “missing context,” working on a project can feel overwhelming and you will feel lost.

Getting context is hard and takes time. A colloquial principle that is broadly accurate is that it takes about 6 months to a year to have enough context on a project to get to the point where you are independently productive. Of course, this timeline varies by the experience of the SWE, the size of the project, etc., but the point is that it takes time.

You will not have enough context to really be independently productive on this project, and that’s fine. You’re not a practicing SWE, yet! But a huge part of your job–in engineering or almost anything else–will be working to get context, so that experience is an important part of this project.

Getting Context

When you want to work on an issue, try to get as much context with it as possible:

• What is the specific issue or feature?
• Why was it filed? Does it reference related issues?
• What component is it located in?
• Can you see any approaches to addressing the issue?
• Has it been attempted? What approaches did other people take?
• What will the required work be? Try to estimate what you think the complexity of the issue is.

If you can’t answer some of these questions, you’re missing context for it. If you need more context to be able to make progress, ask for help: send a message in Slack, comment on the issue, etc.

The Logistics

Submitting Code

You and your teammates will do you your work in a fork of their repository. When you want make a pull request to the Application Service repo, you’ll first create a pull request against your own repository (which I and your team will review), and once I’ve reviewed it, you can create a pull request from your fork.

We’ll follow this process to minimize the number of iterations you will have on your PR with the team.

You’ll be responsible for keeping your fork up-to-date and for coordinating your team’s work in the fork.

I will update this document with more specific code review requirements at a later time (and notify you).

Slack

There is a Slack workspace (https://rhodes-comp365.slack.com) that we we will use as a class to communicate with one another and with the Application Services team. You can use the class as a resource when you have questions or want to discuss ideas.

Click this link to accept the workspace invite and join the workspace.

You will create a channel for your individual team in order to discuss and coordinate work on your team.

However, it is important to ask good questions. “My code won’t build” isn’t a question. Questions should be precise, direct, and informed. Specifically:

• Say what you did to try to understand the issue or topic.
• Describe the overall goal that you’re trying to achieve and how your question applies to that goal.
• If you’re asking a question about a problem you’re having, describe the symptoms rather than what you believe the underlying issue to be.

Read Mozilla’s etiquette for their internal Slack. Also, even if you are not interacting with anyone outside Rhodes, we’ll still adhere to Mozilla’s Community Participation Guidelines.

Stand Ups

We will have weekly stand ups on Mondays in order to discuss what you are planning to do that week. During the stand up, you’re team will go around in a circle with me and describe:

• Progress: What did you complete in the past week?
• Goals: What are you going to accomplish this week?
• Blockers: What is keeping you from accomplishing your goals?

Since there’s many of you, we need to be effective. You should take around a minute with these status updates. If you need to ask questions to clear blockers, use the class Slack or follow up afterward with an email or request to meet.

If you need to present, log into this meeting. Be ready with what you want to present when it is your turn.

The purpose of a class-wide stand up (rather than a private team-only stand up with me) is that I think it will be helpful for gaining context as a class.

Note that this process is probably going to change as the semester progresses. We will have some flexibility here.

The Grades

My expectation for this course is that every student is making meaningful and regular contributions to their group (and to the project).

Since each issue or task differs in scale, I am going to have difficulty assessing your work using objective metrics. That, unfortunately, is also how the real world works–regardless of discipline.

My plan is this:

• Your weekly status report should include the attributed contributions and work of your team.
• Each week, I will assess the work of each team member and assign a score of 1–5:
  1. Did not contribute.
  2. Needs improvement; contributing, but maybe only ideas or in meetings.
  3. Needs improvement; contributing, but irregularly or only with minor things.
  4. Meeting expectations.
  5. Exceeding expectations.
• At the end of the semester, you will receive a score for your work that is the average of your scores, minus the lowest two values.
• I will distribute scores via Slack DMs.

As with the syllabus, I reserve the right to change this as the semester progresses. You won’t lose credit for what you’ve done, though. And if I do make changes, they’ll be announced and this document will be updated. You will also have an opportunity to discuss proposed changes in class.

The Technical Details

Building on Linux

The VM image I distributed at the beginning of class needs to have some libraries and binaries installed in order to build.

Run the following:

sudo apt-get -y install ninja-build \
  libz-dev \
  llvm \
  clang \
  clang-format \
  libclang-dev \
  libxcb-render0-dev \
  libxcb-shape0-dev \
  libxcb-xfixes0-dev

Then, inside your application-services directory:

git clone https://chromium.googlesource.com/external/gyp.git tools/gyp
wget https://bootstrap.pypa.io/ez_setup.py -O - | python2.7 - --user
cd tools/gyp/
sudo python2.7 setup.py install

You should be able to pick up from here and follow the build instructions, beginnning with running the bootstrap script.

After this, cargo test --all should succeed. Note that your VM needs more than 4GB of memory in order for all unit tests to pass. If you want to increase the memory allocated to your VM, shut the VM down, and go to the settings menu, then the “System” tab.

The Final Words

Realize that this is a work-in-progress. I’m aware of other collaborations between open source projects and university classes, but none are quite this format. We will be figuring a lot of things out as we go.

At the end of the day, the value of this experience is that you will gain experience working on real software and understanding/be a part of the process of SWE work.