This extension to the README is necessary for all developers working on the {projectName} codebase.

Build Process

As described in the README, the many steps of assembling, installing, and managing the site have been combined into a few simple commands using Grunt Drupal Tasks.

You can see a list of all available actions by running grunt help.

Build the Codebase

Our build process downloads all upstream dependencies of the site to assemble a functional docroot.

Create build/html directory
Validate custom code with static analysis checks
Download operational dependencies
Set up symlinks from docroot to custom code.

When To Run

First Run: npm install && grunt
After Merging Changes from Upstream: grunt
Before Final Feature Branch Push: grunt

If package.json has changes, you may need to re-run npm install.

Role of Each Dependency Manager

This action cuts across several different dependency managers, which are each used to control the use of different types of external, Open Source libraries. The table below illustrates how the downloaded libraries and modules are used by the system.

Tool	Config Files	Production	Build & Deployment	QA & Development
Composer	composer.json	?	✔	✔
Drush Make	project.make	✔	✗	✔
npm	package.json	✗	✔	✔
Bundler	Gemfile	✗	✔	✔

Installing the Drupal Site

{Run grunt install to install the Drupal site after you've run the main build process.}

Git Practices

Changes committed to master should be ready for production.
Change committed to develop should be technically approved and believed complete by the developer.
Most work should be done in feature branches, named such as feature/KEY-123/short-description and bug/KEY-246/short-description.
Commit messages should always begin with KEY-123: , then follow with 20-60 characters explaining the change.
Never commit CSS or other assets generated by the build process.

All changes should be submitted for code review using a Pull Request. Pull Requests should target the develop branch. If you submit the PR before you've done end-to-end testing and code validation on your change include [WIP] in the PR title so reviewers know it's not ready for merge.

Coding Practices

Development on {projectName} will follow these best practices.

Code Structure and Naming Things

Drupal coding & commenting standards
Commented out code is technical debt and should be avoided.
- Must always have comments describing
  - the change the code would create
  - the condition in which the code is uncommented
  - the condition in which the code is removed
- All developers are responsible for reviewing this each time they come across the code in a new development task.
Correct spelling when naming things. CamelCase and snake_case is okay, but inconsistent abbreviations, acronyms, and word contenation without separators is not.
Kit standard naming conventions. Where this does not make sense we will use the project namespace "{namespace}" as a substitute for the module's unique name (event from {namespace}_event). For example the subtitle field is used across types, but the address field used by events is not, this gives us field_{namespace}_subtitle and field_event_address.

Some of these guidelines are verified by the grunt phpcs task, which is run as part of grunt validate, in turn a step of the overall build process.

Code Layout and Scope

All markup should be defined in templates kept in the theme.
API functions should be maintained at the bottom of the .module file or kept in a separate include file.
Form callbacks should contain the minimum code to interact with the Form system, otherwise they should call API functions for options lists, validation logic, and submit handling.
Menu callbacks should always be in a separate file from .module.
hooks should be implemented in the following thematic order:
- bootstrapping the site
- defining menu routes
- defining permissions, access control, and authentication
- manipulating data structures
- content display

grayside/CONTRIBUTING.md