proj00 : First look at Legacy Code (counts towards lab grade)

num ready? description assigned due
proj00 true First look at Legacy Code (counts towards lab grade) Thu 02/01 04:00PM Fri 02/09 05:00PM

Before you begin this lab, you should be officially assigned to a mentor and to a pair, and you should work in that pair and with that mentor.

If you have not yet been assigned to a mentor and pair, please contact your TA or instructor.

Together with your pair partner, you will do the following steps. Note: this list is just an overview of the entire process, so that you can see a short list of all the things you need to do. You’ll have to consult the rest of the instructions for details.

  1. Consult the seating charts for the 4pm, 5pm and 6pm sections to see which legacy code project your pair was assigned.
    • Be sure that the page accurately reflects your mentor, github id, pair partner, and pair partner’s github id.
    • If you are not on the list, or if there is any error consult a mentor, TA or instructor to fix it.
  2. Then, find the legacy repo to which you’ve been assigned. If you haven’t been assigned a repo, ask your mentor to assign you and your pair partner to a repo.
  3. Once you’ve been assigned to a repo, the pair partner with the github id that comes “first” in the alphabet should fork the repo (as a public repo) to their own githubid. We’ll call this person “pair partner 1”.
    • Forking should have been covered in lecture before this project is assigned; if you are not clear on the details, ask your mentor for assistance.
  4. Then, pair partner 1 should add pair partner 2 as a collaborator.
  5. Whoever is driving, clone the forked repo to the computer where you are working (this may be a directory on CSIL, or it may be your own laptop or desktop machine. If it is your own computer, you’ll need to install Java 8 and whatever build tool you using (Ant, Maven, Gradle, etc.)

  6. Once you have cloned the forked repo, create a file called W18_proj00.md in the root directory of the repo. In this file, at the top, put both pair partner’s names (if you prefer you may use first name last initial, e.g. Selena G., Justin T.)

  7. In that file, using Markdown formatting, write answers to the questions listed below in the section W18_proj00.md instructions below. There are more detailed instructions below.
  8. Commit that file to the forked repo, then do a pull request back to the ucsb-cs56-projects repo you forked from.
    • If you are not sure how to do a pull request, ask your mentor for guidance.

Then you are finished with proj00, and your first encounter with legacy code.

Note: It is okay to create public forks of these legacy labs but not okay to create public repos for other labs where the instructions indicate to create a private repo. Please be careful to note the difference.

Find the list of “issues” for the project, and read through them.

For each repo, there is a list of known “issues”.

You’ll be trying to understand those issues, as well as determine additional issues that could be added.

In the end, you are doing the steps you’d need to do to “get ready” to take on this as your legacy code project.

W18_proj00.md instructions

Your next set of steps will be, in general, to learn about the project, and write about the current state of the project Your goal is to understand what the project is about, identifying things that are good, and things that could be improved.

In the root directory of your forked copy of the project repo, add a file called W18_proj00.md in which you write a short assessment of your findings.

This file W18_proj00.md should include the following. (If you are having trouble knowing how to complete these steps, read through the rest of the lab instructions, including the “frequently asked questions” section below before asking for help.)

When you are done… do a pull request

When you are finished, do a pull request back to original repo that you forked from. The pull request will typically only be the change of adding your W18_proj00.md, unless you went ahead and made some changes to improve the project. If you did, those changes will count towards a future project grade.

Your mentor will comment on the pull request, and then your TA will “accept” the pull request when your submission is graded. The grade will put into Gauchospace, and your feedback will be added to your feedback repo.

Frequently Asked Questions

Is this the project we’ll be working on the rest of the quarter

Maybe yes, maybe no. Its partially up to you.

You will be given that option—but you’ll also have the option to switch to another project. So part of this exercise is also to see whether you think this project is interesting enough that you want to stick with it, or whether you want to trade away for some other project.

If you trade away, then you’ll contribute your project into a “pool” of available projects. Once that pool is established, you’ll be invited to rank the projects in that pool by your preferences. Then, based on preferences plus an element of random chance to break ties, we’ll make a second project assignment. You are not guaranteed to get your first choice, but historically, most folks have gotten their first, second, or third choice in that second round.

If we find things that need to be fixed, should we fix them?

Note that ACTUALLY making code changes is NOT part of this lab. You MAY do that, but it isn’t necessary at this stage.

Why it might be a good idea to go ahead:

Why it might be a good idea to wait:

I don’t even know where to start. Can you help?

If you are having trouble getting started, I suggest that together with your pair partner, you take turns driving/navigating through these steps. You can use regular or strong-style pairing, as you see fit.

  1. Put your name, your partner’s name, and each of your github ids in the file.
  2. Read the README.md file and try to understand what the project is about.
  3. Read the “issues” on github.com (these will be on the ORIGINAL repo that you forked from) and try to understand what each one is asking the programmer to do.
  4. Run the ant build.xml file with ant -p and see what the ant targets are. Then also look into the build.xml file directly—if there are some targets that don’t have description elements but SHOULD, that’s something to notice.
  5. Try compiling and running the code and see if the code actually works or not.

Once you’ve done all of that, invite your mentor to come over and talk with you about the repo you were assigned. Your mentor will likely be familiar with the project already—over the last couple of weeks, they spent some time looking at it. Along with your mentor, come up with a plan for some things you can do in about 2-3 hours time that can improve the code somewhat. These may include:

  1. Writing proposals for improving the README (perhaps with screenshots, developer documentation, and build/usage instructions)
  2. Identifying bugs with the project
  3. Looking at test coverage (and noting which portions of the project have no test coverage)
  4. Suggesting additional features and adding them as issues
  5. Identify portions of codebase that can be cleaned up and refactored and create corresponding issues
  6. Commenting on existing issues to ask clarifying questions, or point out any parts of the issues that are unclear. Ask yourself—if I were assigned to work on this, would I know what to do and where to start? Or would I be confused and have questions? If its the latter, ask the questions in the comments.

Code related stuff:

  1. Identify uncommented portions of codebase, add normal and Javadoc comments to that portion of codebase, and/or change variable and method names to ones that make comments unnecessary/superfluous.
  2. Read build.xml and attempt to identify unnecessary/obsolete/confusing portions of build script and make corresponding issues.
  3. Checking package names to see whether they correspond to the preferred naming convention for legacy code projects.
  4. Check public, private, “package private” for attributes and methods.
  5. If there are objects that have too much functionality bundled into them, but they should be refactored into multiple smaller objects, make this observation.

Write all of your observations in the W18_proj00.md file.

What happens after this lab?

In your next encounter with legacy code, you’ll start working on the “issues” that you read about during your first encounter, either for this same project, or for some other project to which you are assigned.

We’ll update you on how the next round will go, and what your choices are in terms of staying with the project to which you were initially assigned, or possible switching to a different project.


http://ucsb-cs56-w18.github.io/lab/proj00