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.

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.
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.
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.
Then, pair partner 1 should add pair partner 2 as a collaborator.
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.)
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.)
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.
- Don’t know Markdown? Check out this cheat sheet!
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”.

These are found on github.com on the ORIGINAL repo that you forked from, the one under https://github.com/ucsb-cs56-projects
They will not be on your forked copy.
IMPORTANT: When adding new issues, you will add them directly on the ucsb-cs56-projects version of the repo, not on the forked copy.

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.)

(a) (20 pts) A brief description of the project. Here, I’m looking for a short description: probably 1 sentence, 2-3 at most.
(b) (20 pts) a set of user stories (as a X I can Y so that Z) that describe what the current software in its current state can do.
- First, review how User Stories are supposed to be written.
(c) (20 pts) a brief assessment of whether the software runs or not. If it runs, briefly describe what it does,
(d) (20 pts) a set of user stories (at least 2, but you are encouraged to write up to 4 or more if you can, as many as you think is reasonable) about features that COULD be added to the software to make it more useful, fun, better, etc.
- Again, review the preferred way to write User Stories.
(e) (20 pts) An assessment of the current quality of the README.md. What information could be added to make it easier for the next generation of folks maintaining this code to use the software, and/or maintain the software?
(f) (20 pts) An assessment of the current state of the build.xml file if applicable, or if the project has been converted to Maven or Gradle, note this.
- If it’s based on Ant, Are there targets that need descriptions? Is there old legacy JWS stuff that needs to be removed? (More on this below).
- It it’s based on Maven or Gradle, is there sufficient documentation in the README.md that someone new to those tools has the information they need to get started?
(g) (20 pts) An assessment of the current “issues”. Are there enough issues that you could earn 1000 points by working on this project? Are the issues clear in terms of what the expectations are?
(h) (20 pts) A list of additional issues that you may have added, if any. For each, a link to the issue is good enough.
(i) (100 pts) Most important: an assessment of the actual code. Write a bit about how the code is organized. Are the purposes of the classes, and their methods clear? Is it obvious how the classes relate to one another? Is the code easy to read and understand? If you had to give someone else that was going to work on the code just “one screenful of text” to help that programmer get up to speed quickly, what information would you convey?
(j) (40 pts) Related to code quality, but factored out into a separate issue because it is so important: how is the test coverage? Are there JUnit tests at all? If so, how much of the project is covered by testing? Are there opportunities to expand test coverage, and if so, how would you go about it?

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:

If you DO decide, together with your pair partner, that you WANT to take this project on as your legacy code project for the course, then you MAY go ahead and start making those changes.
If you do, you’ll be a little bit “ahead” of the work you need to do later in the quarter.
You might need to fix a few small things just to be able to compile and run. Feel free to do that.

Why it might be a good idea to wait:

If you are NOT going to be taking on this project as YOUR legacy code project, but instead, are planning to take your chances on the second round selection process, you might be doing extra work by starting now.

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.

Put your name, your partner’s name, and each of your github ids in the file.
Read the README.md file and try to understand what the project is about.
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.
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.
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:

Writing proposals for improving the README (perhaps with screenshots, developer documentation, and build/usage instructions)
Identifying bugs with the project
Looking at test coverage (and noting which portions of the project have no test coverage)
Suggesting additional features and adding them as issues
Identify portions of codebase that can be cleaned up and refactored and create corresponding issues
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:

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.
Read build.xml and attempt to identify unnecessary/obsolete/confusing portions of build script and make corresponding issues.
Checking package names to see whether they correspond to the preferred naming convention for legacy code projects.
Check public, private, “package private” for attributes and methods.
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.