Skip to content

Developer Best Practices

Changes to Digital Rebar, including documentation, are managed through our source code management process. This ensures robust control over the code base and enables RackN to curate the project to ensure quality.

Commit Message Format

The following format is expected (eventually enforced) for all commit messages. This format helps us assemble changelog entries and release notes.

Commit Message first Line format: tag(area): description

Use one of the following tags:

  • build: Changes that affect the build system or external
  • dependencies (example scopes: gulp, broccoli, npm)
  • ci: Changes to CI configuration files and scripts (example scopes: Travis, Circle, BrowserStack, SauceLabs)
  • docs: Documentation only changes
  • feat: A new feature
  • fix: A bug fix
  • perf: A code change that improves performance
  • refactor: A code change that neither fixes a bug nor adds a
  • feature
  • style: Changes that do not affect the meaning of the code
  • (white-space, formatting, missing semi-colons, etc)
  • test: Adding missing tests or correcting existing tests

Examples are areas include (but are not limited to):

  • [piece]: Server changes should list specific area. (e.g. dhcp, frontend, backend, wal, ha, manager, ...)
  • api: dr-server api
  • cli: drpcli code
  • [name]: plugin module (e.g. raid, rack, bios, ipmi, ...)
  • [name]: content directory (e.g. task-library, drp-community-content, ...)
  • ux: RackN ux

The list of things within the area field can be comma separated.

Examples:

  • feat(dhcp): option 82 processing
  • fix(cli): allow list operations to be sorted on return
  • feat(backend,frontend,wal): manager objects are embedded in core
  • feat(ux): Search of documentation part of helper bar
  • doc(vmware): fix alignment of documentation headers.

After the first line, you should have a blank line, then at least a paragraph describing what the commit is changing and why. Do not assume that the reader of the commit will be able to understand what and why by reading the source code -- you as the author right now understand what changed and why, but others (including Future You) probably will not at first glance. A few minutes and a few paragraphs describing what and why now will save possibly hours puzzling the what and why out several years down the road. As an added bonus, detailed commit messages make it much easier to build detailed release notes.

Some good background reading on how to write good git commit messages: * How To Write a Good Commit Message goes into more detail. * On Commit Messages is an older post. but still relevant. * Writing Commit Messages goes into great detail on what makes a good commit message.

TL;DR: Be kind to your peers and your future self. Write detailed commit messages.