Skip to content

Latest commit

 

History

History
115 lines (91 loc) · 5.4 KB

0016-programming-style-guide.md

File metadata and controls

115 lines (91 loc) · 5.4 KB
Raw

Paketo Project Programming Style Guide

Summary

This RFC proposes a Programming Style Guide for the Paketo project. It will be used to evaluate and polish pull requests, educate contributors, and overall maintain consistent code quality in the project.

Motivation

The Programming Style Guide will address the challenge of maintaining consistent and high-quality code with excellent test coverage in an open source project. Explicitly naming expectations will benefit both contributors of new code and reviewers of that code in the following ways:

  • Contributors (and especially first-time contributors) will have a standard against which to evaluate their work before opening it to outside feedback. They can address problems before reviewers see them.
  • Contributors can refer to the Style Guide during ideation to understand which of their ideas are likely to a) be useful and b) play well with existing elements of the project.
  • Reviewers can ground their feedback by citing a centralized Style Guide that may include more complete explanations of common feedback.
  • Reviewers can be confident that their feedback covers the most important bases (i.e. those outlined in the Style Guide)

Maintaining a Style Guide also improves the fairness and inclusivity of the project. Reviewers and contributors can ground their efforts in a set of explicit and agreed upon standards, which reduces the barrier to entry for new contributors to the project. Furthermore, standards-based feedback reduces the amount that implicit biases about whose work is "high quality" come into play.

Detailed Explanation

The Style Guide should be placed in the paketo-buildpacks/community repository, where other information for new contributors is located. To implement this RFC, we should:

  1. Create STYLEGUIDE.md in paketo-buildpacks/community and populate it with the initial guide outlined in the Implementation section of this RFC.
  2. Add a link to the Style Guide to the pull request template for the paketo-buildpacks organization (located here), perhaps as an additional checkbox asking people to check out the guide.

Rationale and Alternatives

  1. Do nothing. For example, the CNB project functions as an open source community without a contribution Style Guide.
  2. Maintain a private set of contribution guidelines that only maintainers (as PR reviewers) have access to.

While it's clear that open source projects can function without Style Guides, the effort required to create one is not tremendous. See the sections above for discussion of what the benefits of a Style Guide are. Keeping the Style Guide public and accessible to contributors before they submit pull requests is more in the spirit of open source transparency. It also affords contributors the opportunity to self-edit pull requests before submitting them to maintainers. A well-written, publicly available Style Guide can increase code quality and consistency in a project while transferring some of the responsibility of maintaining code quality from maintainers onto contributors themselves.

Implementation

The proposed initial Paketo Project Style Guide is as stated below. Note that this is an initial guide, which can be revised via subsequent RFCs to the paketo-buildpacks/community repository in which the style guide will be placed.

Style Guide

Buildpack Design Best Practices

  1. Keep Detect and Build functions as small as possible.
  2. Only add a requirement to a buildpack if it's necessary for the buildpack to run.
  3. Only add a provision to a buildpack if it actually supplies something for itself or a subsequent buildpack to use.

Testing

  1. Please write tests for your contributions to the Paketo project.
  2. If your contribution changes or adds to the API of a buildpack, you'll likely need to change or add integration tests.
  3. If your contribution changes how the detect or build executables of a buildpack work, you'll likely need to change or add unit tests.

Preferred Code Structures

  1. Many Paketo buildpacks are written in Go. If you are contributing Go, please write Effective Go.

  2. When reviewing Pull Requests, maintainers may refer to these Common Go Code Review Comments.

  3. If you're writing in a shell scripting language, keep this Shell Style Guide in mind.

    • In particular, check out the "When to use Shell" section to consider if it's time to switch languages.

Prior Art

Unresolved Questions and Bikeshedding

{{Write about any arbitrary decisions that need to be made (syntax, colors, formatting, minor UX decisions), and any questions for the proposal that have not been answered.}}

{{REMOVE THIS SECTION BEFORE RATIFICATION!}}