For project 2, you will gain experience with using the git
distributed version control system and associated collaboration tools
on GitHub. You will make several contributions to a repository of
lecture notes from class.
While I make class recordings available to enrolled students, I do not release my personal lecture notes. Your task on this assignment will be to collectively create and curate lecture notes for this class. In doing so, you will create, and comment on, several GitHub issues. You will make contributions to the official repository by means of pull requests (PRs) from your personal fork of the repository.
This project will last the duration of the semester (since you will be constructing lecture notes), but there will be one checkpoint to give you feedback.
As part of this project, you must:
Because this assignment runs the duration of the semester, we will also
schedule a checkpoint so that you can receive some feedback on your
use of git. This will give you time to make changes to your practices
and improve your final grade.
For the checkpoint, you will be required to:
Lecture notes must be formatted as Markdown files. You might find referring to the Markdown Guide helpful for learning more about valid formatting. It is also possible to preview Markdown using Visual Studio Code (and other editors).
You must decide on a specific convention for notes with your peers. (Hint: this could be a reasonable issue to open and comment on.) Part of your grade will depend on the uniformity of the lecture notes format. It may take a little while for you to decide on a format, which means that some number of pull requests might be made to resolve formatting errors.
Similarly, the directory structure and file naming conventions are for you to decide with your peers.
The main repository for this project is located at https://github.com/kevinaangstadt/CS340-Summer21-Notes. Note that you do not have write access to this repository, nor will you be granted write access to this repository. This means that you cannot push to this repository. Instead, you will need to make contributions following the techniques we discussed in class.
You will be contributing to the main project repository through both issues and pull requests.
When creating issues, please be sure to provide descriptive prose of the issue you are reporting. Issues can be used for discussing/requesting new "features" (new notes, for example) as well as reporting problems with existing content. This assignment does not specify precisely what you and your peers should use issues for, but you might consider:
Once someone creates an issue, you will have the opportunity to add your own comments. While these comments are not necessarily graded, these will help you to plan with your peers how to address the issue.
Additonally, consider trying out some of the advanced issue features, such as assigning an issue to a user and applying tags to the issues to categorize them.
You do not have write access to the main project repository. Therefore, you must make a fork of the repository and submit your contributions as pull requests. Recall our discussion of pull requests from class: you will want to provide a meaningful message with your pull request and also follow best practices for organizing your commits. Please refer to the High-Quality Commit Messages section for more details.
Create your pull requests from non-main branches. That is, create a
new branch with a descriptive name before committing your contributions
to your fork. Failure to open a pull request from a separate branch
will result in your pull request being rejected. Note that this isn't
always necessary, but this project is giving you a chance to practice
with using git.
Similarly, your pull request will be rejected if there are merge conflicts with the main project repository. This means you might need to update your PR to address other changes that are contributed to the repository.
As part of this project, you will be assigned one pull request from a peer to review. Your job in reviewing this PR is to:
Note that you may lose points if you approve a contribution that does not meet our guidelines or fail to adequately justify your decision.
As part of this project, you will be graded on the quality of your commit messages. Further, the quality of your commits will also be judged.
In general, we will be following the guidelines laid out here (and inlined below).
Further, look through Open Stack's Git Commit Practices for tips on how to break up commits in reasonable ways. This guide also provides some examples of high- and low-quality commit messages.
This assignment is perhaps different from any of your other CS assignments.
In some sense, we're less interested in the content
you create and more interested in the process
you follow. Further, git can be frustrating to use, so
this project gives you a fairly low-stakes venue to practice. We are
using course notes in this project so that you do not also have to expend
mental power on implementing a correct program. Our class notes are
also not private, and thus we can keep our repositories publicly visible.
You might note that your score does not actually reflect the quality of notes that you are contributing. Instead, our focus is on the quality of the commits, issues, and pull requests that you create. It is still in your best interest to create high-quality notes, but this will likely occur through revisions and additional contributions. This more closely mimics the reality of a job (or grad school) where producing high-quality work is an iterative process.
You are allowed to be strategic on this project. For example, it is entirely reasonable to contribute notes that don't adhere to your formatting conventions so that there is an opportunity to open an issue and submit a pull request. By the end of the project, you will want to ensure that your fomatting is consistent.
While you are working on this project, keep some notes about things you learn or struggle with. This information will help you as you are writing your final reflection.
Recall that you can reorganize your commits by using git rebase
and git cherry-pick.
You must also write a short two-paragraph report reflecting on your
experience contributing to a git repository. In addition to these
two paragraphs, your report should also contain references for any
resources you used to help complete this assignment.
The first paragraph should address the challenges you faced and concepts you learned. Rather than write this as a chronological narrative, organize your prose around key themes. If a particular task took you a while or took you multiple tries to get correct, focus some of your description here.
The second paragraph should reflect on the processes you and your peers developed for the repository. You might focus on some of the positive and negative aspects of using issues/pull requests as opposed to other mechanisms. Further, you might comment on the organization of files and writing conventions you and your peers chose to use.
Finally, your written report should contain your list of references used for completing this assignment.
Submit this report as a PDF on Gradescope. Any other format may cause you to lose points on this asignment.
You do not need to submit any files to Gradescope for the checkpoint. You will be graded based on your contributions to the main project repository.
For the final project submission, you should submit your written report on Gradescope.
P2 Grading (out of 50 points):