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