Expected duration
5 hours per team member
Deadline
2359 on Lessons 14 and 25 and 34
Points
25 points

Assignment

Project artifacts will reside in a Git repository, which provides a permanent record of all changes. The basic workflow is

  1. clone the project repository,
  2. create a branch for your changes,
  3. make changes,
  4. commit the changes, and
  5. create a pull request for those changes.

If you aren’t comfortable with Git, then you should review the resources listed in the configuration management lesson.

Specifics regarding the implementation – that is, the code or other artifacts that you will be creating – should be detailed in your specification. Because they vary for each project, further details cannot be detailed here.

Recommendations

The following recommendations are designed to help you avoid common implementation pitfalls.

Specifications

As you start your implementation activities, you will likely have an open pull request for your specification. It is imperative that you address the comments and questions so that the specification is (eventually) accepted. Hence, you should allocate time to complete the work that you’ve started. In some cases, there are only a few minor comments that must be addressed. In other cases, you may be requested to make substantial revisions to your initial specification.

The temptation is to rush ahead, attempting to complete the implementation as quickly as possible. Don’t do it! First, if the foundation (i.e., the specification) isn’t solid, then you aren’t going to be able to deliver anything of quality. Second, grades depend on what is approved for each sprint, which is the purpose of the specification. If substantial revisions have been requested to your specification, then it’s likely that you’ll be doing a lot of rework. True story: When I was leading a team that was contributing security features to OpenStack, we had to rewrite a feature three times because we failed to reach consensus on the design with the rest of the community. Don’t make this mistake yourself.

Pull Requests

When committing anything to the repository, remember that each “logical change” should have its own pull request. A logical change may be a complete specification, the cleanup of existing source code (e.g., reformatting it to follow an agreed-upon coding standard), or the addition of a feature. In general, the following should be avoided:

Mixing functional and non-functional changes
Create separate commits for the non-functional change (e.g., code cleanup) and the functional change; starting with the former ought to simplify the latter.
Mixing two unrelated functional changes
Break the changes apart into separate pull requests.
Having a giant pull request for a feature
Start with the minimum functionality that provides business value (i.e., value to the end user) and add capability incrementally.
Mingling auto-generated with hand-written code
Often a gotcha when using web frameworks, clearly delineate the project initialization (e.g., the scaffolding provided by the framework) from its project-specific modifications to aid with review.

Typically this means that each pull request changes fewer than 200 lines of code. Why is this limit important? Larger commits are more difficult to review, increasing the likelihood of mistakes. In addition, knowing the context for the change (e.g., who changed the line and why it was modified) is often critical to maintain the system’s functionality during later refactoring.

Submission

To “submit” your implementation changes, create a pull request in GitHub. Your team may have one or more pull requests for your implementation activities.

The pull request triggers a review of the proposed changes so that you have feedback and the opportunity to address any questions or issues. Expect to iterate on your changes, using the feedback to improve the initial version – it’s rare for any software engineering artifact to be “right” the first time.

Grading

The implementation changes will be graded at the end of the sprint and is based on their final versions (i.e., incorporating all updates from the review process). If you implement everything in your specification and the corresponding pull request(s) merged, then you will earn full credit for the implementation. Conversely, unaddressed comments on the pull request(s) indicate that you’ll receive a low score because there are remaining opportunities for improvement.

Your goal should be to address the feedback as thoroughly and as quickly as possible to ensure that the implementation changes are approved and earn full credit for this assignment. Take advantage of the iterative review process – the quality bar is high precisely because that’s what expected in real software projects.

Rubric

The following grading rubric will be used for this assignment:

Superb (100%)
All functionality in specification implemented. Pull request(s) approved / merged.
Proficient (90%)
All functionality in specification implemented. Trivial issues (e.g., code style and minor refactoring for clarity), but no design flaws and passes all tests, including tests for new functionality
Competent (75%)
Major functionality in specification implemented, but may lack complete testing. Pull request has a single issue that requires resolution, such as a minor design flaw or test failure.
Marginal (50%)
Some functionality in specification implemented, but implementation is obviously incomplete. Pull request has multiple issues that require resolution, such as design flaws and test failures, requiring significant rework.
Unsatisfactory (25%)
Little functionality in specification implemented. Pull request is obviously incomplete with multiple issues that require resolution.

Resources

Git Commit Good Practice

Project sprints implementation overview