1 |
caf16a48
|
Assos Assos
|
<!-- @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 |
eefc2ac0
|
Assos Assos
|
Bootstrap and Bootswatch are compile from
|
82 |
|
|
`starterkits/less/less/overrides.less`. Typically, this task generates hundreds
|
83 |
|
|
of files and can take upwards of \~10 seconds to fully complete.
|
84 |
caf16a48
|
Assos Assos
|
|
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 |
eefc2ac0
|
Assos Assos
|
The following is just a template to show a typical structured format used as
|
108 |
|
|
release notes for this project:
|
109 |
caf16a48
|
Assos Assos
|
|
110 |
|
|
```html
|
111 |
|
|
<h3 id="change-records">Change Records</h3>
|
112 |
|
|
<!-- Change records table HTML -->
|
113 |
|
|
|
114 |
|
|
Optionally, you can insert any additional verbiage here.
|
115 |
|
|
However, if it is long, it should really be a change record.
|
116 |
|
|
|
117 |
|
|
<p> </p>
|
118 |
|
|
<h3 id="notes">Notes</h3>
|
119 |
|
|
|
120 |
|
|
<p> </p>
|
121 |
eefc2ac0
|
Assos Assos
|
<p>Changes since <!-- tag --> (<!-- commit count -->):</p>
|
122 |
caf16a48
|
Assos Assos
|
|
123 |
|
|
<h3 id="features">New Features</h3>
|
124 |
|
|
<ul>
|
125 |
|
|
<li><!-- Issue/Commit Message --></li>
|
126 |
|
|
</ul>
|
127 |
|
|
|
128 |
|
|
<h3 id="bugs">Bug Fixes</h3>
|
129 |
|
|
<ul>
|
130 |
|
|
<li><!-- Issue/Commit Message --></li>
|
131 |
|
|
</ul>
|
132 |
|
|
```
|
133 |
|
|
|
134 |
|
|
### Create a Release Node
|
135 |
|
|
|
136 |
|
|
{.alert.alert-info} **NOTE:** This project currently relies on the
|
137 |
|
|
[Drush Git Release Notes](https://www.drupal.org/project/grn) tool to
|
138 |
|
|
automatically generate the the bulk of the release notes. This does, however,
|
139 |
|
|
requires maintainers to do the following extra steps. This entire process will
|
140 |
|
|
eventually be converted into a fully automated grunt task. Until then, please
|
141 |
|
|
download and install this tool and follow the remaining steps.
|
142 |
|
|
|
143 |
|
|
1. Create a [tag in git](https://www.drupal.org/node/1066342) that follows the
|
144 |
|
|
previous version and push it to the repository.
|
145 |
|
|
2. Create a [project release node](https://www.drupal.org/node/1068944) for this
|
146 |
|
|
newly created tag.
|
147 |
|
|
3. _(Skip this step if this is a new "alpha/beta" release)_ In a separate tab,
|
148 |
|
|
go to this project's [releases](https://www.drupal.org/node/259843/release)
|
149 |
|
|
page. Open and edit the previous release node. It should have followed the
|
150 |
|
|
release note template. If it has, copy and paste its contents into the new
|
151 |
|
|
release node body.
|
152 |
|
|
4. In a separate tab, go to the [change records](https://www.drupal.org/list-changes/bootstrap)
|
153 |
|
|
for this project and filter by the new official release version
|
154 |
|
|
("alpha/beta/RC" releases should always use the next "official" version for
|
155 |
|
|
their change records). If there are no change records, then remove this
|
156 |
|
|
section. Otherwise, copy and paste the entire table into the template
|
157 |
|
|
(replacing any existing one, if necessary).
|
158 |
|
|
5. Generate a list of issues/commits by executing the following from the root
|
159 |
|
|
of the project:
|
160 |
|
|
|
161 |
eefc2ac0
|
Assos Assos
|
`drush release-notes <old> <new> --commit-count`
|
162 |
caf16a48
|
Assos Assos
|
(e.g. `drush release-notes 7.x-3.0 7.x-3.1 --commit-count`)
|
163 |
|
|
|
164 |
|
|
If this is a follow-up "alpha/beta/RC" release, always use the last
|
165 |
|
|
"alpha/beta/RC" release version instead. This will allow for a quicker
|
166 |
|
|
parsing of the list to merge into the previously copied release notes:
|
167 |
|
|
|
168 |
eefc2ac0
|
Assos Assos
|
`drush release-notes <old> <new> --commit-count`
|
169 |
caf16a48
|
Assos Assos
|
(e.g. `drush release-notes 7.x-3.1-beta2 7.x-3.1-beta3 --commit-count`)
|
170 |
|
|
|
171 |
|
|
6. Copy the entire generated output into the template, just under where the
|
172 |
|
|
"Change Records" section would be, replacing only the commit count (do not
|
173 |
|
|
replace the "since last {offical} version").
|
174 |
|
|
7. Go though each item (`<li>`) that contains an issue link, ignoring duplicates
|
175 |
|
|
and standalone verbiage (direct commits). Move (cut and paste) these items
|
176 |
|
|
into the appropriate "New Features" or "Bug Fixes" sections.
|
177 |
eefc2ac0
|
Assos Assos
|
8. Once complete the generated list should be empty (e.g. `<ul></ul>`), remove
|
178 |
|
|
it.
|
179 |
caf16a48
|
Assos Assos
|
9. Save the release node. |