topic Maintainers

Generally speaking, these topics will not be very helpful to you unless you are a maintainer for this project. If you're simply curious about the process or even want to help improve this aspect of the project, all suggestions will be appreciated!

Prerequisites

For development, this project relies heavily on NodeJS/Grunt to automate some very time consuming tasks and to ensure consistent output. If you do not have these CLI tools, please install them now:

Installation

This project's installation may initially take a while to complete. Please read through the entire topic before continuing and be aware of what to expect. Suffice it to say: you will not have to manually update this project again.

After you have installed the prerequisite CLI tools, run npm install in this directory. This will install the necessary NodeJS modules inside the node_modules directory.

After NodeJS has finished installing its own modules, it will automatically invoke grunt install for you. This is a grunt task that is specifically designed to keep the project in sync amongst maintainers.

Drush

There are several commands available to run, please execute drush to view the full list. This topic only covers the commands this project created.

drush bootstrap-generate-docs or drush bs-docs

Generates markdown documentation for the Drupal based code. Possible arguments are:

  • type: The specific type of documentation to generate, defaults to all. Possible values: all|settings

Grunt

There are several tasks available to run, please execute grunt --help to view the full list of tasks currently available. This topic only covers the most important or commonly used tasks.

grunt install

This task is automatically invoked as a postinstall event of npm install. There should be no need to manually invoke this task. However, if you feel the need to manual invoke this task, you may do so without fear of producing any unintended side-effects. This is simply an alias for sub-tasks defined below.

grunt githooks

This is a sub-task of grunt install. It will automatically install the necessary git hooks for this project. These git hooks allow the project to keep track of changes to files in order to automate and ensure certain files are committed (e.g. compiled CSS files). Do not worry, if you already have existing git hook files in place, this will work around them.

Any time there is a change to package.json, Gruntfile.js, .githooks.js.hbs or any of the files in the grunt subdirectory, the npm install task will automatically be executed by the git hook itself. This allows the workflow to be altered by one maintainer and those changes propagated to the others the next time they pull down the repository.

grunt sync

This is a sub-task used by grunt install. It will automatically download and install the various 3.x.x versions of the Bootstrap and Bootswatch libraries for local development purposes in the ./lib directory. This process utilizes Bower and can initially take a while for it to fully complete.

Once you have the various versions of libraries have been installed, this task becomes much faster. This task utilizes the jsDelivr API to determine which versions to install. To avoid abusing API calls, this list is cached for one week as the .libraries file in the root of this project. In the event that a new list needs to be generated and the week cache expiration has not lifted, you can either simply remove the file manually or run grunt sync --force to force an API call and generate a new list.

grunt clean-vendor-dirs

This is a sub-task used by grunt install. Drupal currently does not exclude vendor directories when scanning directories of modules/themes to look for .info files. Some NodeJS modules actually are installed with files that have this same extension, yet cannot be parsed by Drupal. Due to the nature of how Drupal currently parses these files, it can cause a PCRE recursion in PHP. This ultimately leads to a segmentation fault and thus rendering the site inoperable. For more details, see: https://www.drupal.org/node/2329453

grunt compile

This task ensures that all the necessary variations of versions and themes of Bootstrap and Bootswatch are compile from starterkits/less/less/overrides.less. Typically, this task generates hundreds of files and can take upwards of ~10 seconds to fully complete.

Optionally, if the --dev parameter is specified, this task will only compile the starterkit's overrides.less file for the latest version of Bootstrap:

  • ./css/<%= latestVersion/overrides.css
  • ./css/<%= latestVersion/overrides.min.css

grunt watch

This task is responsible for watching various source files and executing the appropriate tasks these source files are normally consumed by. With the caveat of long compilation times mentioned in the previous section, it is highly recommended running this task as such: grunt watch --dev. Keep in mind that this limits the rapid development of the overrides.less file to the default Bootstrap theme. If you have switched themes, you must manually compile all the version and theme override files.

Releases

This project attempts to provide more structured release notes. This allows the project to communicate more effectively to the users what exactly has changed and where to go for additional information. This documentation is intended for the project maintainers to help provide consistent results between releases.

Release notes template

The following is just a template to show a typical structured format used as release notes for this project:

<h3 id="change-records">Change Records</h3>
<!-- Change records table HTML -->

Optionally, you can insert any additional verbiage here.
However, if it is long, it should really be a change record.

<p>&nbsp;</p>
<h3 id="notes">Notes</h3>

<p>&nbsp;</p>
<p>Changes since <!-- Last major release version (no dev/beta/rc) --> (<!-- Total commit count -->):</p>

<h3 id="features">New Features</h3>
<ul>
  <li><!-- Issue/Commit Message --></li>
</ul>

<h3 id="bugs">Bug Fixes</h3>
<ul>
  <li><!-- Issue/Commit Message --></li>
</ul>

Create a Release Node

NOTE: This project currently relies on the Drush Git Release Notes tool to automatically generate the the bulk of the release notes. This does, however, requires maintainers to do the following extra steps. This entire process will eventually be converted into a fully automated grunt task. Until then, please download and install this tool and follow the remaining steps.

  1. Create a tag in git that follows the previous version and push it to the repository.

  2. Create a project release node for this newly created tag.

  3. (Skip this step if this is a new "alpha/beta" release) In a separate tab, go to this project's releases page. Open and edit the previous release node. It should have followed the release note template. If it has, copy and paste its contents into the new release node body.

  4. In a separate tab, go to the change records for this project and filter by the new official release version ("alpha/beta/RC" releases should always use the next "official" version for their change records). If there are no change records, then remove this section. Otherwise, copy and paste the entire table into the template (replacing any existing one, if necessary).

  5. Generate a list of issues/commits by executing the following from the root of the project:

    drush release-notes <last official version> <new version> --commit-count (e.g. drush release-notes 7.x-3.0 7.x-3.1 --commit-count)

    If this is a follow-up "alpha/beta/RC" release, always use the last "alpha/beta/RC" release version instead. This will allow for a quicker parsing of the list to merge into the previously copied release notes:

    drush release-notes <last alpha/beta/RC version> <new alpha/beta/RC version> --commit-count (e.g. drush release-notes 7.x-3.1-beta2 7.x-3.1-beta3 --commit-count)

  6. Copy the entire generated output into the template, just under where the "Change Records" section would be, replacing only the commit count (do not replace the "since last {offical} version").

  7. Go though each item (<li>) that contains an issue link, ignoring duplicates and standalone verbiage (direct commits). Move (cut and paste) these items into the appropriate "New Features" or "Bug Fixes" sections.

  8. Once complete the generated list should be empty (e.g. <ul></ul>), remove it.

  9. Save the release node.

Source docs/Maintainers.md (line 3)