1 <!-- @file Maintaining the Drupal Bootstrap project. -->
5 Generally speaking, these topics will not be very helpful to you unless you are
6 a maintainer for this project. If you're simply curious about the process or
7 even want to help improve this aspect of the project, all suggestions will be
11 For development, this project relies heavily on NodeJS/Grunt to automate some
12 very time consuming tasks and to ensure consistent output. If you do not have
13 these CLI tools, please install them now:
19 This project's installation may initially take a while to complete. Please read
20 through the entire topic before continuing and be aware of what to expect.
21 Suffice it to say: you will not have to manually update this project again.
23 After you have installed the prerequisite CLI tools, run `npm install` in this
24 directory. This will install the necessary NodeJS modules inside the
25 `node_modules` directory.
27 After NodeJS has finished installing its own modules, it will automatically
28 invoke `grunt install` for you. This is a grunt task that is specifically
29 designed to keep the project in sync amongst maintainers.
32 There are several commands available to run, please execute `drush` to view the
33 full list. This topic only covers the commands this project created.
35 ### `drush bootstrap-generate-docs` or `drush bs-docs`
36 Generates markdown documentation for the Drupal based code. Possible arguments are:
37 - **type:** The specific type of documentation to generate, defaults to `all`.
38 Possible values: `all|settings`
41 There are several tasks available to run, please execute `grunt --help` to view
42 the full list of tasks currently available. This topic only covers the most
43 important or commonly used tasks.
46 This task is automatically invoked as a `postinstall` event of `npm install`.
47 There should be no need to manually invoke this task. However, if you feel the
48 need to manual invoke this task, you may do so without fear of producing any
49 unintended side-effects. This is simply an alias for sub-tasks defined below.
52 This is a sub-task of `grunt install`. It will automatically install the
53 necessary git hooks for this project. These git hooks allow the project to keep
54 track of changes to files in order to automate and ensure certain files are
55 committed (e.g. compiled CSS files). Do not worry, if you already have existing
56 git hook files in place, this will work around them.
58 Any time there is a change to `package.json`, `Gruntfile.js`, `.githooks.js.hbs`
59 or any of the files in the `grunt` subdirectory, the `npm install` task will
60 automatically be executed by the git hook itself. This allows the workflow to
61 be altered by one maintainer and those changes propagated to the others the
62 next time they pull down the repository.
65 This is a sub-task used by `grunt install`. It will automatically
66 download and install the various 3.x.x versions of the Bootstrap and Bootswatch
67 libraries for local development purposes in the `./lib` directory. This process
68 utilizes Bower and can initially take a while for it to fully complete.
70 Once you have the various versions of libraries have been installed, this task
71 becomes much faster. This task utilizes the jsDelivr API to determine which
72 versions to install. To avoid abusing API calls, this list is cached for one
73 week as the `.libraries` file in the root of this project. In the event that a
74 new list needs to be generated and the week cache expiration has not lifted,
75 you can either simply remove the file manually or run `grunt sync --force` to
76 force an API call and generate a new list.
78 ### `grunt clean-vendor-dirs`
79 This is a sub-task used by `grunt install`. Drupal currently does not exclude
80 vendor directories when scanning directories of modules/themes to look for
81 .info files. Some NodeJS modules actually are installed with files that have
82 this same extension, yet cannot be parsed by Drupal. Due to the nature of how
83 Drupal currently parses these files, it can cause a PCRE recursion in PHP. This
84 ultimately leads to a segmentation fault and thus rendering the site inoperable.
85 For more details, see: https://www.drupal.org/node/2329453
88 This task ensures that all the necessary variations of versions and themes of
89 Bootstrap and Bootswatch are compile from `starterkits/less/less/overrides.less`.
90 Typically, this task generates hundreds of files and can take upwards of \~10
91 seconds to fully complete.
93 Optionally, if the `--dev` parameter is specified, this task will only compile
94 the starterkit's `overrides.less` file for the latest version of Bootstrap:
96 * `./css/<%= latestVersion/overrides.css`
97 * `./css/<%= latestVersion/overrides.min.css`
100 This task is responsible for watching various source files and executing the
101 appropriate tasks these source files are normally consumed by. With the caveat
102 of long compilation times mentioned in the previous section, it is highly
103 recommended running this task as such: `grunt watch --dev`. Keep in mind that
104 this limits the rapid development of the `overrides.less` file to the default
105 Bootstrap theme. If you have switched themes, you must manually compile all
106 the version and theme override files.
109 This project attempts to provide more structured release notes. This allows the
110 project to communicate more effectively to the users what exactly has changed
111 and where to go for additional information. This documentation is intended for
112 the project maintainers to help provide consistent results between releases.
114 ### Release notes template
115 The following is just a template to show a typical structured format used as release notes for this project:
118 <h3 id="change-records">Change Records</h3>
119 <!-- Change records table HTML -->
121 Optionally, you can insert any additional verbiage here.
122 However, if it is long, it should really be a change record.
125 <h3 id="notes">Notes</h3>
128 <p>Changes since <!-- Last major release version (no dev/beta/rc) --> (<!-- Total commit count -->):</p>
130 <h3 id="features">New Features</h3>
132 <li><!-- Issue/Commit Message --></li>
135 <h3 id="bugs">Bug Fixes</h3>
137 <li><!-- Issue/Commit Message --></li>
141 ### Create a Release Node
143 {.alert.alert-info} **NOTE:** This project currently relies on the
144 [Drush Git Release Notes](https://www.drupal.org/project/grn) tool to
145 automatically generate the the bulk of the release notes. This does, however,
146 requires maintainers to do the following extra steps. This entire process will
147 eventually be converted into a fully automated grunt task. Until then, please
148 download and install this tool and follow the remaining steps.
150 1. Create a [tag in git](https://www.drupal.org/node/1066342) that follows the
151 previous version and push it to the repository.
152 2. Create a [project release node](https://www.drupal.org/node/1068944) for this
154 3. _(Skip this step if this is a new "alpha/beta" release)_ In a separate tab,
155 go to this project's [releases](https://www.drupal.org/node/259843/release)
156 page. Open and edit the previous release node. It should have followed the
157 release note template. If it has, copy and paste its contents into the new
159 4. In a separate tab, go to the [change records](https://www.drupal.org/list-changes/bootstrap)
160 for this project and filter by the new official release version
161 ("alpha/beta/RC" releases should always use the next "official" version for
162 their change records). If there are no change records, then remove this
163 section. Otherwise, copy and paste the entire table into the template
164 (replacing any existing one, if necessary).
165 5. Generate a list of issues/commits by executing the following from the root
168 `drush release-notes <last official version> <new version> --commit-count`
169 (e.g. `drush release-notes 7.x-3.0 7.x-3.1 --commit-count`)
171 If this is a follow-up "alpha/beta/RC" release, always use the last
172 "alpha/beta/RC" release version instead. This will allow for a quicker
173 parsing of the list to merge into the previously copied release notes:
175 `drush release-notes <last alpha/beta/RC version> <new alpha/beta/RC version> --commit-count`
176 (e.g. `drush release-notes 7.x-3.1-beta2 7.x-3.1-beta3 --commit-count`)
178 6. Copy the entire generated output into the template, just under where the
179 "Change Records" section would be, replacing only the commit count (do not
180 replace the "since last {offical} version").
181 7. Go though each item (`<li>`) that contains an issue link, ignoring duplicates
182 and standalone verbiage (direct commits). Move (cut and paste) these items
183 into the appropriate "New Features" or "Bug Fixes" sections.
184 8. Once complete the generated list should be empty (e.g. `<ul></ul>`), remove it.
185 9. Save the release node.