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.

Requirements

As part of this project, you must:

• Create markdown files for one (1) lecture or appendix. This should be submitted as a pull request to the main project repository. This PR must be accepted to count. Lectures with a scheduled exam do not count and contributions should not overlap. An appendix may be one of the following:
  • Style Guide
  • Course Overview
  • Exam 1 study guide
  • Exam 2 study guide
• Submit an additional one (1) pull request to the main project repository on a contribution that is not yours. This PR must be accepted to count.
• Create at least two (2) non-superfluous issues on the main project repository.
• Comment on issues that your peers post.
• Review one pull request that is assigned to you by the instructor.
• Provide high-quality commit messages, pull request descriptions, and issue comments.

Checkpoint

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:

• Contribute one pull request (PR) that is an outline for your selected page. This is an additional PR from the requirements above. It does not need to have any content populated in the outline.
• Create one issue on the main project repository. This issue counts toward your required issues for the final submission.
• Follow our class guidelines for high-quality commit messages.

Lecture Note Format

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: one student gets to contribute this convention, but many could provide input on an issue.) 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.

Main Project Repository

The main repository for this project is located at https://github.com/kevinaangstadt/CS340-S23-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.

Contributions

You will be contributing to the main project repository through both issues and pull requests.

Issues

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:

• Planning who will be responsible for which lecture days.
• Discussing and agreeing on formatting guidelines.
• Reporting errors or problems in existing content.

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.

Pull Requests (PRs)

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 in real projects, 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.

Reviewing

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:

• Verify the correctness of the contribution
• Review the commit orginization and make sure that it follows the best practices we discussed.
• Ask for changes if needed.
• Write a comment explaining your reasons for approving the PR once you are satisfied that everything is in order.

Note that you may lose points if you approve a contribution that does not meet our guidelines or fail to adequately justify your decision.

High-Quality Commit Messages

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.

Commentary

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.

Written Report (README)

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.

What to Submit for P2

Checkpoint

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.

Grading Rubric

P2 Grading (out of 50 points):

• 15 points: Checkpoint
  • 5 points — create one pull request before the deadline
  • 5 points — create one issue before the deadline
  • 5 points — quality of prose and organization of commits
• 8 points: Pull requests
  • Four points per accepted pull request (up to the maximum number of points)
  • Up to four points are for PRs for new content. Up to fourt points are for PRs for revisions.
• 2 points: Issues
  • One point per issue opened (up to the maximum number of points)
• 8 points: Review of assigned PR
  • 8 — Review is thorough, ensures that the contribution or revisions are correct (both in content and format), and the comment approving the PR is descriptive.
  • 6 — Review is good, but might have allowed some mistakes in the contributions. The comment approving the PR, however, is descriptive.
  • 4 — Review is adequate, but might have allowed some mistakes in the contributions. The comment approving the PR, lacks sufficient description.
  • 2 — Review fails to catch many errors in the contributed PR or the approving comment is extremely terse, without much detail.
  • 1 — Review is completed, but lacks nearly all required level of detail.
  • 0 — Assigned review is not completed.
• 10 points: Quality of commit, issue, and PR messages
  • To receive full credit, nearly all of your contributed commits, issues, and PRs must have proper formatting, including descriptive message bodies.
  • Failure to adhere to our course guidelines for high-quality messages will result in a reduction on this score.
  • Use feedback you receive from the checkpoint to improve this score on your final project submission.
• 5 points: Written report
  • 5 — a two-paragraph report reflecting on your activities using git. One paragraph the challenges faced and concepts you learned. The second paragraph reflects on teh processes you and your peers developed for the repository.
  • 4 — a reasonable report, but lacking a solid description of one or more aspects or significantly exceeding the length limit.
  • 3 — a brief report, detailing only half of the required information, but mentioning both required topics.
  • 2 — a brief report, detailing only half of the required information.
  • 1 — a terse or uninformative report.
  • 0 — No README file provided.
• 2 points: References
  • 2 — References are provided as part of the final report and contain a list of resources used for this assignment. This includes course materials.
  • 1 — References file exists, but does not adequately identify resources used for this assignment.
  • 0 — No references file provided.