Style Guide

Style Guide

General Wording

Wording matters. If you're not sure, ask!

All requirements should adhere to RFC-2119 conventions, but in the spirit of agile, understand that epics and stories (issues) are conversation starters and should be discussed within each thread, so these are subject to change.

Changes in stated requirements must be highlighted within the issue discussion thread.

Coding Styles

To help enforce these practices, Codacy is evaluating this project. While these settings will likely require tweaks, they should provide a basis from which to analyze the codebase.

Spaces or Tabs

There exists an ongoing debate in nearly every development community for best practices.

This project uses spaces with the number specified according to this programming language style guide. A .editorconfig file is included to make this less burdensome on contributors by automatically converting the tab key to the appropriate number of spaces for the code type.

PHP

All PHP code should PSR-2 styling and conventions for all application code.

For test code, deviations from PSR-2 are permissible in order to increase the readability of the test.

A code linter will be employed for automated scanning of application code, it is a best practice to run this yourself as well. Suggestions are welcome for which linter best runs these verifications.

JavaScript

As with all things in the JavaScript community, this seems an ever-moving target. This project is willing to adopt any preferred convention as long as it is consistent and can be checked with a code linter.

Git Strategy

Branching

This project leverages the popular Git-Flow as a general rule. If you're not currently using it, consider learning more about git flow.

tl;dr all work is done in feature branches, these merge to develop which branches a release which is then merged back into both develop and master. Hotfixes are based on master and closed on merge to master and develop.

Advantages

This method ensures that:

• the master branch has a tag for each commit layer, which matches production releases exactly
• the develop branch holds the latest features ready for testing and quality assurance
• each new feature is broken into a features/[description] branch for direct tracing of activities
• new release candidates are built in a release/[semanticVersion] branch to do last minute changes before releasing to production
  • version increments
  • dependency lockdown/updates
• hotfixes are supported

With its convenient plugin for Mac and Windows development platforms, even with simple understanding of the CLI concepts, the convention is easy to follow.

Pull Requests

All PRs

• should follow the style guidelines
• must maintain or increase test coverage
• reference the story/issue they address
• call out any new dependencies added by the PR
• check PR build results and resolve any issues
• be made against the develop branch, or explain special circumstances why they are made against another

Commit messages

Commit messages should reference the story/issue addressed, and must include a brief summary of the change proposed (this should be about 72 characters in length). The summary should be followed by a paragraph description of the change, intent, and explanation of any decisions made as part of the commit. This helps frame the story and lead to more meaningful code review feedback.

In this vein, a PR should consist of several small commits instead of one large one. Incremental progress is easier to follow and review and a more natural workflow.

Merging

An ongoing debate continues in many open source communities around how this is best accomplished. For this organization, all merges should be conducted as rebase actions.

If you're new to rebase-ing or have unanswered questions this introduction blog post is excellent. This practice maintains the overall revision tree.

The workflow is slightly more complex, but the long-term benefits make it worth it to learn. Check out the workflow here.