Project protocol

In order to help you become the best software developers you can be, we have collected a set of guidelines, expectations, and procedures below that we expect you to learn and follow during the course of your project development in this class.

Generally speaking the instructors are open to debate over these, and nothing is written in stone. As such, they may change over time for the better, and changes will be announced. If you do have an issue with these, let us know, since following the protocol as the graders understand it is important for getting the highest grades possible.

Table of contents

1. Assignment workflow
   1. Assignment tracker
2. Tech Leads
3. Pair programming
4. Code changes
5. Code style
6. Tests
7. Project hygiene

Assignment workflow

With some exceptions, assignments will be conducted as teams, with the aim of replicating the work environment of a professional software developer as much as possible. In order to work on the assignments as a team, for each assignment you should:

• Read the assignment to familiarize yourself with the requirements, and think of how you and your team could accomplish the assignment in your codebase.

• Shortly after the assignment is published, you should meet as a team over videoconference, or via chat if that’s not possible, at a time where everyone can reasonably attend. During this meeting you should:
  1. Discuss and agree upon on a plan of action.
  2. Split the assignment into small tasks.
  3. Choose due dates / estimated completion dates for each task to allow tasks that need to be made serially (in a fixed order, dependent on the order) to be done in time for the assignment due date.
  4. Assign tasks to individuals based on availability. Each person on the team coding that week should have roughly the same amount of work If there are not enough tasks to go around or the work is unbalanced, try to find some general health tasks to assign that week (like improving test coverage, adding documentation, or cleaning up the code base). As a last resort, you may consider pair programming.
  5. Note all decisions made and individuals involved in the assignment tracker.

• Then, write code for your assigned task(s), making sure to adhere to the task requirements as closely as possible. If requirements need to be made, you should consult with the team as soon as possible to update your team’s plan of action.

• Send code out for review, paying attention to the expectations around code changes.

• Submit your code well in advance of the project deadline, especially if other members of the team need to make follow-up changes.

Assignment tracker

Each team should create and maintain a Google Document in which they keep their team meeting notes and track assignment progress. Each team should do the following once:

• Create a new document.
• Share the document to each member of your team (using their @g.ucla.edu address), and ucla-cs130-admin@googlegroups.com with edit access.
• Insert the template below.

For each assignment, you should duplicate a new Assignment section and place it at the beginning of the document, then create and maintain Tasks and Meetings sections thoughout the course of the assignment, matching the template as sensibly as possible.

Tech Leads

For each assignment, one person will serve as the project Tech Lead (TL). You must choose a TL at the time of team formation and rotate through them on a rotating basis. You will be allowed to coordinate swaps as necessary to allow for some flexibility.

Each person will be TL at least twice, and each person must be TL once before anyone does it twice. This means everybody will be a TL at least once during the first half of the class, and again during the second half of the class. This allows you to get some practice early on and a second chance to do even better the second time around.

The TL will be responsible, and graded on:

• Coordinating the weekly team meeting to find when everyone can attend.
• Conducting the team meeting.
• Resolving any disputes about project strategy, acting as a tie breaker for decisions when necessary. (Note, if everyone else wants to do something one way and you are the outlier, you need to convince others to follow you, not just mandate them!)
• Updating (and maintaining) the assignment tracker with tasks, assignments, attendance and other notes as suggested in the template.
• Reviewing all changes submitted by the team that week. Reviews should be completed within at most 24 hours, hopefully much sooner. TLs should be the only people on the team giving a +1 score to allow changes to be submitted. If changes must be urgently submitted before a TL can review, the TL is expected to review the change and record a +1 score after submission, as soon as possible. If changes are requested after submission, they may be addressed in a follow-up change by the original author.
• Making sure that all aspects of the assignment are completed.
• Submitting the “team” version of the assignment submission form.

The TL should not submit any code for compilation, but may (and is encouraged) to submit documentation, make configuration changes, and perform other non-coding tasks (such as making changes to the Google Cloud portions of the project via the Google Cloud Console UI, or gcloud).

TLs will be mainly graded on how well their team completes the assignment in a given week, in addition to performing their TL responsibilities.

Pair programming

Pair programming can be a useful exercise when tackling unusually difficult problems, or when a large chunk of work cannot feasibly be split further to accommodate multiple contributors on the team (though this situation should be very rare). It can also be a very convenient cover for people to try to skate by in this course without doing very much actual work. In order to facilitate the former while preventing the latter, we require the following when pair programming:

• Pair programmers must be documented in the meeting notes, as well as in the description of the change.
• One person in the pair will be the submitter, who will actually be at the keyboard and uploading the change to the code review server under their name. The other person in the pair will be the reviewer.
• When uploading a change for review, the submitter should send include both the reviewer and the TL as change reviewers.
• Reviewers must reply with a 0 score and a comment confirming they pair programmed that change (“I confirm I pair programmed this change.”) within 5 minutes of the change being uploaded to Gerrit.
• The reviewer should then perform a full code review of the code and ensure that what they thought they were programming is what the submitter typed, followed with a 0 score and a comment of “LGTM” (Looks Good To Me). If any changes are to be made, they should note that instead, and iterate with the submitter on the change until they are ready to say “LGTM”. The TL will still have to review the code and give a +1 score to allow submission.
• Pair programming participants cannot be the reviewer multiple times without being a submitter. If pair programming multiple times, you must alternate and be the submitter about as many times as you are a reviewer.

The above must be followed in order to get full credit on the individual coding grade of your assignment.

Code changes

Changes should be focused on one particular task, or one particular sub-component of a task. Changes should be as small as reasonably possible. (They should be big enough to still compile and pass tests!) Generally speaking tests should be added at the same time new code is added, even though it is technically possible to split the two.

When composing a description for the change, focus on describing why the change needs to happen. The code should already be clear enough that anyone on your team can figure out what it does. Suppose, that you bring a new teammate (== you after a week has passed and your memory faded) and they have to review your code, the change description should give enough context that they could figure out what goal it seeks to accomplish and why that’s important to the project. When relevant also add other information to assist reviewers: How the change accomplishes its intent or Testing work that demonstrates completion.

#What Updates authentication to support passwordless @google.com login.

#Why According to #ticket-3 >70% of our users have a google.com email and surveys from PR #ticket-8 show requests for smoother password-less logon using accounts such as Facebook or Google.

#How When a user attempts to sign in they'll have an option to use an email/password or click a google-login button that steps through the oauth flow in <design doc link>, using redirect /oauth_login/google/user?access_token.
Screenshots of the login screen in design doc <link>.

#Testing
 - Added a test account test-user-login@google.com
 - Added selenium tests that exercise the login

If you need to perform a refactoring (like a method rename) as part of a task, make a change that does just the refactoring, and send that out before adding new code or functionality. Purely syntactic or mechanical changes are easier to correctly review than changes to logic or behavior. Changes that combine both to many files are the hardest to review.

In order to account for delays in review, you should be sending changes for review well in advance of the due date, since proper review can require multiple rounds of changes. Do not wait until the night before the due date!

With these in mind, students writing code for an assignment should find a way to submit at least two non-trivial changes per week.

Code style

Code should be written with readability in mind. We will go into this in detail through lectures, but in short it should be:

• Nicely formatted
• Commented where appropriate
• Display stylistic consistency with the rest of the codebase
• Structured into files and directories reasonably, and with intent
• Understandable by someone else, such as a teammate, grader, TA, or instructor
• Carefully peer reviewed

Tests

Your code should be comprehensively tested where possible through unit tests, which should consider a variety of edge cases and operation scenarios. You should always run tests before submitting code, and make sure you do not submit code that breaks tests.

Your server should be tested with integration tests to verify high-level operations. The operation of these tests should also be maintained through code submissions, and should be used to find bugs before submitting code.

Project hygiene

You will be setting up a continuous build on Google Cloud to build, test, compute test coverage, and package your server after every code submission. It is your team’s responsibility to:

• Ensure the build passes and remains passing after every code submission
• Unit test coverage numbers remain high through new code submission
• Integration tests are expanded to cover new high-level server functionality / capability

At the end of every assignment we will examine your build history and your unit test coverage. You will be graded in part on how high your unit test coverage is at the assignment submission time. Your team may be penalized according to the amount of time that your build was broken througout the assignment week.