Advice on successful partnership

Written by Julie Zelenski

We designed the CS107 assignments (even this last one) to be a task appropriate for one person but we also thought it valuable to give you the chance to explore working with a partner if you choose. Many of the CS follow-on courses include group projects, so consider this an optional trial run for figuring out the dynamics of working successfully in a team. It can be both fun and frustrating to work on a team project.

Be thoughtful about choosing where to enter a partnership and be picky about finding the right partner for you. You want a partner with similar expectations about how you will do the work, under what scheduling constraints, and to what standard you have set your sights. You also want someone you trust and can communicate with. The drawbacks to being in a bad partnership than far outweigh any benefits. Working solo has its own set of advantages, not the least of which is total control and ownership of the experience and lack of drama. For this CS107 assignment in past, between third to half of the students have chosen to work individually, the rest pair up.

Logistics

• The allocator implementation is not a candidate for a divide-and-conquer approach. The three functions (malloc/realloc/free) are intimately related and do not easily separate into independent coding tasks. You'll do best to work together at a shared computer, leveraging both brains simultaneously, as you do in lab. We highly recommend adopting a pair programming approach. The basic gist is that one partner acts as the "driver" (typing/editing) and the "passenger" rides along, making observations, pointing out issues, asking questions, suggesting alternatives, etc. Switch roles frequently. The code won't be written any faster than a single coder, but it can be of higher quality, show more thoughtful design, handle more cases, exhibit fewer bugs, and so on. And perhaps both of you will come away with a deeper understanding because of the give-and-take and have more fun along the way!
• You and your partner will need to coordinate sharing your code. There are a couple of possible approaches for how to set up your repo(s), see the section below on "Shared mercurial repos" for details.
• Choose one partner to submit your joint work. The submit script will ask for the partner's name so that both students are properly credited. If you submit more than once, we prefer that the same partner initiate the subsequent submits rather than switching between partners.
• The joint submission is graded once and both partners receive the same score.

Partners and the Honor Code

The Honor Code has a special meaning for partners. The two of you can freely collaborate, but both should contribute equally to the partnership. It is a Honor Code violation to make a submission under two names that represents mostly one person's efforts. Both the partner with limited participation and the partner who agrees to it can be held accountable for the misrepresentation of the work as a joint effort.

Partnership is monogamous-- you may not add a partner or switch to a new partner mid-stream. If a partnership dissolves, the two partners may evolve the joint work into individual submissions. These submissions should clearly credit the ex-partner.

A student who is retaking the course may not re-use the design, code, or documentation from any previous effort. The prohibition against re-use applies regardless of whether the original submission was partnered or individual. The best approach to avoiding problems is to discard all work from the past, as it can be a temptation that you're better off without.

Options for shared mercurial repos

This advice comes courtesy of Peter Johnston, former CS107 TA.

Coordinating changes across a team is one of the key benefits of a revision control system, but... so far your experience with Mercurial has been single-clone and managing multiple clones brings up new challenges. Below we walk you through two possible ways to coordinate access between you and your partner. Our primary recommendation is for Option 1 (single shared repo and a pair programming approach), but we also sketch Option 2 (one master + two partner clones) if you are willing to deal with the more complex merging from parallel development lines. Thoroughly read the instructions for the option you choose and be sure you understand and follow the appropriate workflow.

1. Single shared repo (recommended)

   A continuation of the one-clone-per-project approach you have used all quarter is to create one clone and share it. This version is simple and particularly suited to pair programming. One partner clones normally to create a single repo and then gives permissions to the other partner to directly access it.

   Below we show how Alice (sunet alice) creates the one repo and shares it with her partner Bob (sunet bob). Replace alice and bob with your and your partner's sunets when you execute these commands.

   Alice clones the initial repository into her home directory, then grants access to her partner Bob and removes access for other users:

   hg clone /afs/ir/class/cs107/repos/assign7/$USER ~alice/a7_shared
   
   /afs/cs/software/bin/fsr setacl ~alice/a7_shared bob write 
   /afs/cs/software/bin/fsr setacl ~alice/a7_shared system:anyuser none
   

   Alice accesses a7_shared normally in her home directory. Bob can cd to ~alice/a7_shared to access the shared repo. Both partners can edit files and make commits in this shared repo.

   To test your setup, Alice should cd to the shared repo, edit the readme.txt to add her name, save, and commit. Next Bob should cd to shared repo, add his name to readme.txt, save, and commit. If you encounter problems, reach out on forum/office hours/email to resolve before going further before going further.

   There is only one repo, so there will be no need to sync/merge multiple repos. Both partners can edit/commit in the shared repo. However, the two of you must coordinate your edits. If both of you load allocator.c in your respective editors and try to make concurrent changes, your saves will clobber each other. (There are collaboration-aware editors that can coordinate simultaneous editing sessions, but I digress) To avoid trouble, only one partner should be editing a given file at a time. If using a pair programming approach, this will happen naturally as there is only one driver. The one shared repo is simple to manage and works perfectly with pair programming.

2. One master repo, two partner clones (workable but potential for much hassle due to merge conflicts)

   This is an alternative approach to Option 1. The initial clone is used as a master and each partner makes their own partner clone of the master, for a total of three clones to manage. Each partner works in their own partner clone and pushes updates back to the master and pull partner's updates from the master. The theoretical advantage is that the partners can each work separately, but integrating two parallel lines into one repo can involve some difficult merging -- be forewarned!

   Below we show how Alice (sunet alice) creates the master repo, shares it with her partner Bob (sunet bob), then both Alice and Bob make their own partner clones. Replace alice and bob with the appropriate sunets when you execute these commands.

   Alice clones the initial repository into her home directory to make a master clone grants access to her partner Bob and removes access for other users:

   hg clone /afs/ir/class/cs107/repos/assign7/$USER ~alice/a7_master
   /afs/cs/software/bin/fsr setacl ~alice/a7_master bob write 
   /afs/cs/software/bin/fsr setacl ~alice/a7_master system:anyuser none
   

   Both make a partner clone of the master (each of Alice and Bob execute the command below):

   hg clone ~alice/a7_master ~/a7_mine
   

   Each partner works independently in their own partner clone (their own ~/a7_mine directory). When one of you has an update to incorporate into the master, you commit within your own clone, then issue the hg push command to send those changes to the master. You grab the latest changes from the master into your clone by hg pull and hg update. Each partner pushes their changes to the master and pulls to retrieve their partner's changes from the master. These actions are done regularly to keep in sync with each other.

   To test your setup, Alice should cd to her partner clone, edit the readme.txt to add her name, save, and commit, then push to the master. Bob should then cd to his partner clone, pull/update to get Alice's change, add his name to readme.txt, save, commit and push to master. Alice should then pull/update to get Bob's change. If you encounter problems, reach out on forum/office hours/email to resolve before going further.

   Each of you freely works in your own partner clone with no interference, but must regularly push/pull/update to keep the master repo and partner clones in sync. There can be conflicts when trying to sync if your changes cannot be reconciled with the latest changes of your partner. When you attempt to push/pull, mercurial will report the conflict and require you to hand-merge. The hg merge command will show the two versions plus a third pane for you to merge the two, after which you must commit and push. Reconciling the diffs can be intricate depending on how involved the changes are, so this is where the big downside of the multiple clones is felt. If the two of you are editing on unrelated sections, the push/pull can go smoothly and just be a minor annoyance to keep up with, but the prospect of a messy merge is to be avoided. Confining the edits per-partner to distinct portions of the code is one strategy to simplify the merge operation.

Frequently asked questions about partner work

When I access the repo my partner created, Mercurial complains "untrusted user <my-partner-sunet>". What do I do?

By default, Mercurial doesn't trust hgrc files from other users unless explicitly named. The warning is harmless and you can ignore it, but you can reassure Mercurial that your partner is legit by editing your ~/.hgrc file to add a trusted section (add two lines shown below, replace bob with your partner's sunet):

    [trusted]
    users = bob