revision 1.5.0 → 1.5.2
Sign up to get free protection for your applications and to get access to all the features.
- checksums.yaml +4 -4
- data/README.org +179 -176
- data/lib/revision/releasable.rb +7 -2
- data/lib/revision/version.rb +7 -1
- metadata +3 -3
checksums.yaml
CHANGED
@@ -1,7 +1,7 @@
|
|
1
1
|
---
|
2
2
|
SHA256:
|
3
|
-
metadata.gz:
|
4
|
-
data.tar.gz:
|
3
|
+
metadata.gz: 4668b7330bbac8c0ff2be80e329372715b4e9a1c855324208dad6d0975c3fc53
|
4
|
+
data.tar.gz: 27b0b200fd4e66fc6af0a579d4443d345f08e4205f1e89aafecebf7597d85365
|
5
5
|
SHA512:
|
6
|
-
metadata.gz:
|
7
|
-
data.tar.gz:
|
6
|
+
metadata.gz: 533d69c1f6746f5aeedbbe72420937ed6976eb6dad4dd2ca8a75a7b13df8fa749b65284b137764997f62157a395f42d3ab11f23295b6b5035e14a57b4f524988
|
7
|
+
data.tar.gz: cc6badb780cfff6bae1df61c5697df6c2c37db2221178fe9446c132aabbbe5d0b5a3ced994ca416b292dadef7276b99ef238b46ac502ea7b505955fcd951b05a
|
data/README.org
CHANGED
@@ -1,6 +1,5 @@
|
|
1
1
|
#+TITLE: Revision management gem
|
2
2
|
#+AUTHOR: Cormac Cannon
|
3
|
-
#+EMAIL: cormac.cannon@neuromoddevices.com
|
4
3
|
#+LANGUAGE: en
|
5
4
|
|
6
5
|
# Generic properties
|
@@ -24,250 +23,254 @@
|
|
24
23
|
# or alternatively #+SETUPFILE: theme-readtheorg.setup
|
25
24
|
|
26
25
|
* Overview
|
26
|
+
This gem automates revision management for source projects. The tool is language agnostic (used for C, ruby and matlab projects, to date -- though you're probably better off using bundler for ruby projects). It supports per-project configuration using a yaml-format file called =releasables.yaml= located at the project root.
|
27
27
|
|
28
|
-
|
29
|
-
|
30
|
-
|
28
|
+
It currently supports the following functionality
|
29
|
+
- Manage 3-component revision IDs embedded natively in source file
|
30
|
+
- Embeds/updates/extracts changelog in source file header/footer comments
|
31
|
+
- Automatically prompts for a changelog entry each time a revision identifier is incremented
|
32
|
+
- Optionally commits and tags changes to a git repo after an update to the revision ID
|
33
|
+
- Builds and archives projects in zip format (including release notes and arbitrary release artefacts defined
|
34
|
+
- Deploys
|
31
35
|
|
32
|
-
|
33
|
-
- Manage 3-component revision IDs embedded natively in source file
|
34
|
-
- Embeds/updates/extracts changelog in source file header/footer comments
|
35
|
-
- Automatically prompts for a changelog entry each time a revision identifier is incremented
|
36
|
-
- Optionally commits and tags changes to a git repo after an update to the revision ID
|
37
|
-
- Builds and archives projects in zip format (including release notes and arbitrary release artefacts defined
|
38
|
-
- Deploys
|
36
|
+
Worked on sporadically to allow me to tag, archive and deploy projects in multiple languages in a consistent fashion.
|
39
37
|
|
40
38
|
* Installation
|
41
39
|
** Dependencies
|
42
|
-
|
40
|
+
Ruby / Rubygems installed
|
43
41
|
|
44
42
|
** From rubygems.org
|
45
43
|
|
46
|
-
|
47
|
-
|
48
|
-
|
44
|
+
#+BEGIN_SRC sh
|
45
|
+
gem install revision
|
46
|
+
#+END_SRC
|
49
47
|
|
50
48
|
** From source
|
51
49
|
|
52
|
-
|
53
|
-
git clone git@
|
54
|
-
|
50
|
+
#+BEGIN_SRC sh
|
51
|
+
git clone git@github.com:cormacc/revision
|
52
|
+
#+END_SRC
|
55
53
|
|
56
54
|
|
57
55
|
*** Checkout
|
58
56
|
|
59
|
-
|
60
|
-
|
61
|
-
|
62
|
-
|
63
|
-
|
57
|
+
#+BEGIN_SRC sh
|
58
|
+
gem install bundler
|
59
|
+
git clone git@github.com:cormacc/revision
|
60
|
+
cd revision
|
61
|
+
#+END_SRC
|
64
62
|
|
65
63
|
*** Install
|
66
64
|
|
67
|
-
|
68
|
-
|
69
|
-
|
70
|
-
|
71
|
-
|
72
|
-
|
73
|
-
|
74
|
-
|
75
|
-
|
76
|
-
|
77
|
-
|
78
|
-
|
79
|
-
|
80
|
-
|
81
|
-
|
82
|
-
|
83
|
-
|
84
|
-
|
85
|
-
|
86
|
-
|
87
|
-
|
88
|
-
|
89
|
-
|
90
|
-
|
91
|
-
|
92
|
-
|
93
|
-
|
65
|
+
#+BEGIN_SRC sh
|
66
|
+
bundle install
|
67
|
+
bundle exec rake install
|
68
|
+
#+END_SRC
|
69
|
+
|
70
|
+
#+RESULTS:
|
71
|
+
#+begin_example
|
72
|
+
Using rake 10.5.0
|
73
|
+
Using bundler 1.16.0
|
74
|
+
Using coderay 1.1.2
|
75
|
+
Using diff-lcs 1.3
|
76
|
+
Using git 1.3.0
|
77
|
+
Using method_source 0.9.0
|
78
|
+
Using pry 0.11.3
|
79
|
+
Using rubyzip 1.2.1
|
80
|
+
Using thor 0.19.4
|
81
|
+
Using revision 1.0.0 from source at `.`
|
82
|
+
Using rspec-support 3.7.0
|
83
|
+
Using rspec-core 3.7.0
|
84
|
+
Using rspec-expectations 3.7.0
|
85
|
+
Using rspec-mocks 3.7.0
|
86
|
+
Using rspec 3.7.0
|
87
|
+
Bundle complete! 5 Gemfile dependencies, 15 gems now installed.
|
88
|
+
Use `bundle info [gemname]` to see where a bundled gem is installed.
|
89
|
+
revision 1.0.0 built to pkg/revision-1.0.0.gem.
|
90
|
+
revision (1.0.0) installed.
|
91
|
+
#+end_example
|
94
92
|
|
95
93
|
* Usage
|
96
94
|
|
97
95
|
** Supported Commands
|
98
|
-
|
99
|
-
|
100
|
-
|
101
|
-
|
102
|
-
|
103
|
-
|
104
|
-
|
105
|
-
|
106
|
-
|
107
|
-
|
108
|
-
|
109
|
-
|
110
|
-
|
111
|
-
|
112
|
-
|
113
|
-
|
114
|
-
|
115
|
-
|
116
|
-
|
117
|
-
|
118
|
-
|
119
|
-
|
120
|
-
|
121
|
-
|
122
|
-
|
123
|
-
|
124
|
-
|
125
|
-
|
126
|
-
|
96
|
+
Run the executable with no arguments to get usage instructions in your console window...
|
97
|
+
|
98
|
+
#+BEGIN_SRC sh
|
99
|
+
revision
|
100
|
+
#+END_SRC
|
101
|
+
|
102
|
+
#+RESULTS:
|
103
|
+
#+begin_example
|
104
|
+
Loading releasable definitions from /home/cormacc/dev/gem/revision/releasables.yaml ...
|
105
|
+
Commands:
|
106
|
+
revision --version, -v # print the version
|
107
|
+
revision archive # Archive releasable(s)
|
108
|
+
revision build # Build releasable(s)
|
109
|
+
revision changelog # Display change log on stdout
|
110
|
+
revision deploy # Deploy releasable(s)
|
111
|
+
revision help [COMMAND] # Describe available commands or one specific command
|
112
|
+
revision info # Display info for all defined releasables
|
113
|
+
revision major # Increment major revision index
|
114
|
+
revision minor # Increment minor revision index
|
115
|
+
revision package # Build and archive releasables
|
116
|
+
revision patch # Increment patch revision index
|
117
|
+
revision tag # Commit the current revision to a local git repo ...
|
118
|
+
|
119
|
+
Options:
|
120
|
+
[--dryrun], [--no-dryrun]
|
121
|
+
[--id=ID]
|
122
|
+
|
123
|
+
#+end_example
|
124
|
+
|
125
|
+
#+BEGIN_NOTE
|
126
|
+
The tool can be run from any subfolder of a project root -- it will traverse the tree until it finds
|
127
|
+
an ancestor containing =releasables.yaml= OR can go no further (in which case it throws an error).
|
128
|
+
#+END_NOTE
|
127
129
|
|
128
130
|
*** Operating on multiple releasables
|
129
131
|
|
130
|
-
|
131
|
-
|
132
|
-
|
133
|
-
|
132
|
+
A single =releasables.yaml= file can define multiple releasables, either implicitly (via inclusion) or explicitly
|
133
|
+
(see [[Configuration]] section below for examples). In this context, the ~info~ and ~archive~ commands
|
134
|
+
will operate on all defined releasables, whereas the remaining commands will require the releasable
|
135
|
+
to be specified using the ~--id=~ option, e.g.
|
134
136
|
|
135
|
-
|
136
|
-
|
137
|
-
|
137
|
+
#+BEGIN_SRC sh
|
138
|
+
revision minor --id=firmware
|
139
|
+
#+END_SRC
|
138
140
|
|
139
141
|
** Configuration
|
140
142
|
|
141
|
-
|
142
|
-
|
143
|
-
|
143
|
+
YAML syntax is used for the configuration file. The [[Syntax]] and [[Examples]] sections below should provide sufficient
|
144
|
+
introduction to the limit subset of language features required to use this tool, however further info
|
145
|
+
may be found at the following links:
|
144
146
|
|
145
|
-
|
146
|
-
|
147
|
+
- http://docs.ansible.com/ansible/latest/YAMLSyntax.html
|
148
|
+
- http://www.yaml.org/start.html
|
147
149
|
|
148
150
|
*** Syntax
|
149
151
|
|
150
|
-
|
151
|
-
|
152
|
+
The =releasables.yaml= file should contain a top level ~:releasables~ node.
|
153
|
+
Under this, you can create a list (or YAML /sequence/) of releasable definitions.
|
152
154
|
|
153
|
-
|
154
|
-
|
155
|
+
Each sequence item begins with a ~-~ and contains either a link to a folder containing its own =releasables.yaml=
|
156
|
+
defining one or more releasables ...
|
155
157
|
|
156
|
-
|
157
|
-
|
158
|
-
|
158
|
+
#+BEGIN_SRC yaml
|
159
|
+
- :folder: relative/path/to/a/releasable/folder
|
160
|
+
#+END_SRC
|
159
161
|
|
160
|
-
|
162
|
+
... or a single inline releasable definition.
|
161
163
|
|
162
|
-
|
163
|
-
|
164
|
-
|
164
|
+
#+BEGIN_NOTE
|
165
|
+
The lines beginning with '#' are explanatory comments
|
166
|
+
#+END_NOTE
|
165
167
|
|
166
|
-
|
167
|
-
|
168
|
-
|
169
|
-
|
170
|
-
|
171
|
-
|
172
|
-
|
173
|
-
|
174
|
-
|
175
|
-
|
176
|
-
|
177
|
-
|
178
|
-
|
179
|
-
|
180
|
-
|
181
|
-
|
168
|
+
#+BEGIN_SRC yaml
|
169
|
+
- :id: my_releasable
|
170
|
+
:revision:
|
171
|
+
# Source file containing the revision identifier
|
172
|
+
# This will also include changelog entries, embedded as comments
|
173
|
+
:src: lib/revision/version.rb
|
174
|
+
# Regex matching the source revision identifier. Must contain the following named capture groups
|
175
|
+
# - major, minor, patch :: Numeric (uint) sequences representing the three revision ID components
|
176
|
+
# - sep1, sep2 :: the characters separating the revision components
|
177
|
+
# - prefix, postfix :: sufficient syntactic context to match the revision ID uniquely
|
178
|
+
# N.B. this regex matches the version ID from the standard bundler gem skeleton,
|
179
|
+
# e.g. VERSION = "1.1.0"
|
180
|
+
:regex: (?<prefix>VERSION = ")(?<major>\d+)(?<sep1>\.)(?<minor>\d+)(?<sep2>\.)(?<patch>\d+)(?<postfix>")
|
181
|
+
# Comment char for the project language -- prefixed to each line of changelog entries
|
182
|
+
# Quotes only necessary here to prevent # being interpreted as the beginning of a YAML comment
|
183
|
+
:comment_prefix: "#"
|
182
184
|
# Sequence of build steps -- each item should be a valid shell command, prefixed with the YAML sequence item token, '- '
|
183
185
|
:build_steps:
|
184
186
|
- bundle exec rake install
|
185
|
-
|
186
|
-
|
187
|
-
|
188
|
-
|
189
|
-
|
190
|
-
|
191
|
-
|
192
|
-
|
193
|
-
|
194
|
-
|
195
|
-
|
196
|
-
|
197
|
-
|
187
|
+
# Sequence defining the files (build artefacts) to package in the release archive.
|
188
|
+
# Each artefact definition must include a :src: key/value pair.
|
189
|
+
# An optional :dest: value may be provided to rename the file during packaging, or just (as in the first entry below)
|
190
|
+
# to flatten the folder structure.
|
191
|
+
# Any <VER> (or <REV>) in the :src: or :dest: placeholders wil be replaced with the current revision ID
|
192
|
+
# The revision archive will also include the revision history extracted as a text file
|
193
|
+
:artefacts:
|
194
|
+
# A binary artefact -- the
|
195
|
+
- :src: pkg/revision-<VER>.gem
|
196
|
+
:dest: revision-<VER>.gem
|
197
|
+
# This document -- the :dest: value defaults to duplicating :src: if not specified
|
198
|
+
- :src: README.org
|
199
|
+
#+END_SRC
|
198
200
|
|
199
201
|
**** TODO (or at least consider) add support for overridable defaults
|
200
|
-
|
201
|
-
|
202
|
-
|
203
|
-
|
202
|
+
e.g. via a =.releasables= configuration file in the user home dir.
|
203
|
+
Though this would be bad for collaborative development as the config file would live outside source control.
|
204
|
+
Possibly useful to support inclusion of a controlled configuration file instead? Primarily to define
|
205
|
+
a revision regex and comment prefix for a group of related releasables....
|
204
206
|
|
205
207
|
*** Examples
|
206
208
|
**** C project
|
207
209
|
|
208
|
-
|
209
|
-
|
210
|
-
|
211
|
-
|
212
|
-
|
213
|
-
|
214
|
-
|
215
|
-
|
216
|
-
|
217
|
-
|
218
|
-
|
219
|
-
|
210
|
+
#+BEGIN_NOTE
|
211
|
+
The ~:regex:~ and ~:comment_prefix:~ keys are absent in the C example below. This project started life as
|
212
|
+
managing some embedded C projects, and the default values reflect this.
|
213
|
+
#+END_NOTE
|
214
|
+
|
215
|
+
#+BEGIN_SRC yaml
|
216
|
+
:releasables:
|
217
|
+
- :id: mbt_cd_firmware
|
218
|
+
:revision:
|
219
|
+
:src: src/FirmwareRevision.c
|
220
|
+
:build_steps:
|
221
|
+
- make --jobs=8 -f Makefile CONF=bootloadable
|
220
222
|
:artefacts:
|
221
223
|
- :src: dist/bootloadable/production/firmware.production.hex
|
222
224
|
:dest: mbt_cd_firmware_v<REV>.bootloadable.hex
|
223
|
-
|
224
|
-
|
225
|
-
|
225
|
+
- :src: dist/default/production/firmware.production.hex
|
226
|
+
:dest: mbt_cd_firmware_v<REV>.standalone.hex
|
227
|
+
#+END_SRC
|
226
228
|
|
227
229
|
**** Ruby project
|
228
230
|
|
229
|
-
|
230
|
-
|
231
|
-
|
232
|
-
|
233
|
-
|
234
|
-
|
235
|
-
|
236
|
-
|
237
|
-
|
231
|
+
#+BEGIN_SRC yaml
|
232
|
+
:releasables:
|
233
|
+
- :id: revision
|
234
|
+
:revision:
|
235
|
+
:src: lib/revision/version.rb
|
236
|
+
:regex: (?<prefix>VERSION = ")(?<major>\d+)(?<sep1>\.)(?<minor>\d+)(?<sep2>\.)(?<patch>\d+)(?<postfix>")
|
237
|
+
:comment_prefix: "#"
|
238
|
+
:build_steps:
|
239
|
+
- bundle exec rake install
|
238
240
|
:artefacts:
|
239
241
|
- :src: pkg/revision-<VER>.gem
|
240
|
-
|
242
|
+
#+END_SRC
|
241
243
|
|
242
244
|
*** Heirarchical project
|
243
|
-
|
245
|
+
Rather than defining the releasable parameters inline, a =releasables.yaml= list entry can contain a (relative or absolute) link to another folder containing it's own =releasables.yaml=.
|
244
246
|
|
245
|
-
|
246
|
-
|
247
|
+
i.e assuming the earlier examples were in folders =examples/c= and =examples/ruby= relative to a common root, a separate =releasables.yaml=
|
248
|
+
at that root could include them as follows...
|
247
249
|
|
248
|
-
|
249
|
-
|
250
|
-
|
251
|
-
|
252
|
-
|
250
|
+
#+BEGIN_SRC yaml
|
251
|
+
:releasables:
|
252
|
+
- :folder: examples/c
|
253
|
+
- :folder: examples/ruby
|
254
|
+
#+END_SRC
|
253
255
|
|
254
256
|
**** TODO consider supporting a higher-level aggregate revision ID
|
255
257
|
|
256
|
-
|
257
|
-
|
258
|
-
|
258
|
+
#+BEGIN_SRC yaml
|
259
|
+
:revision:
|
260
|
+
:src: release_log.txt
|
259
261
|
:releasables:
|
260
262
|
- :folder: examples/c
|
261
|
-
|
262
|
-
|
263
|
+
- :folder: examples/ruby
|
264
|
+
#+END_SRC
|
263
265
|
|
264
266
|
* Development
|
265
267
|
|
266
|
-
|
268
|
+
After checking out the repo, run =bin/setup= to install dependencies. Then, run =rake spec= to run the tests. You can also run =bin/console= for an interactive prompt that will allow you to experiment.
|
267
269
|
|
268
|
-
|
270
|
+
To install this gem onto your local machine, run =bundle exec rake install=.
|
269
271
|
|
272
|
+
To release a new version, update the version number in =version.rb=. You can do this using the gem, by entering =revision minor= (or =patch= or =major= as appropriate), and then run =bundle exec rake release=, which will create a git tag for the version, push git commits and tags, and push the =.gem= file to [rubygems.org](https://rubygems.org).
|
270
273
|
|
271
274
|
* Contributing
|
272
275
|
|
273
|
-
|
276
|
+
Bug reports and pull requests are welcome on GitHub at https://github.com/cormacc/revision.
|
data/lib/revision/releasable.rb
CHANGED
@@ -141,8 +141,12 @@ module Revision
|
|
141
141
|
"#{@git_tag_prefix}#{revision}"
|
142
142
|
end
|
143
143
|
|
144
|
+
def escape(a_string)
|
145
|
+
a_string.gsub('"',"\\\"")
|
146
|
+
end
|
147
|
+
|
144
148
|
def tag_annotation
|
145
|
-
@revision.last_changelog_entry.join("\n")
|
149
|
+
escape(@revision.last_changelog_entry.join("\n"))
|
146
150
|
end
|
147
151
|
|
148
152
|
def commit_message
|
@@ -153,7 +157,7 @@ module Revision
|
|
153
157
|
commit_lines << "Also..."
|
154
158
|
commit_lines += changelog_entry[2..-1]
|
155
159
|
end
|
156
|
-
commit_lines.join("\n")
|
160
|
+
escape(commit_lines.join("\n"))
|
157
161
|
end
|
158
162
|
|
159
163
|
def tag
|
@@ -162,6 +166,7 @@ module Revision
|
|
162
166
|
puts commit_message
|
163
167
|
system("git commit -a -m \"#{commit_message}\"")
|
164
168
|
puts "Tagging as #{tag_id}"
|
169
|
+
puts "git tag -a #{tag_id} -m \"#{tag_annotation}\""
|
165
170
|
system("git tag -a #{tag_id} -m \"#{tag_annotation}\"")
|
166
171
|
end
|
167
172
|
end
|
data/lib/revision/version.rb
CHANGED
@@ -1,10 +1,16 @@
|
|
1
1
|
# Defines the revision ID for the revision gem
|
2
2
|
module Revision
|
3
|
-
VERSION = "1.5.
|
3
|
+
VERSION = "1.5.2".freeze
|
4
4
|
end
|
5
5
|
|
6
6
|
# <BEGIN CHANGELOG>
|
7
7
|
#
|
8
|
+
# Version 1.5.2 (10 Jun 2020)
|
9
|
+
# - Uprevving around undeletable git tag
|
10
|
+
#
|
11
|
+
## Version 1.5.1 (10 Jun 2020)
|
12
|
+
# - Escape " and ' in commit message when constructing git command line (' still problematic in some shells)
|
13
|
+
#
|
8
14
|
# Version 1.5.0 (13 Feb 2020)
|
9
15
|
# - Now handles multiple deployment destinations in releasables.yaml
|
10
16
|
#
|
metadata
CHANGED
@@ -1,14 +1,14 @@
|
|
1
1
|
--- !ruby/object:Gem::Specification
|
2
2
|
name: revision
|
3
3
|
version: !ruby/object:Gem::Version
|
4
|
-
version: 1.5.
|
4
|
+
version: 1.5.2
|
5
5
|
platform: ruby
|
6
6
|
authors:
|
7
7
|
- Cormac Cannon
|
8
8
|
autorequire:
|
9
9
|
bindir: exe
|
10
10
|
cert_chain: []
|
11
|
-
date: 2020-
|
11
|
+
date: 2020-06-10 00:00:00.000000000 Z
|
12
12
|
dependencies:
|
13
13
|
- !ruby/object:Gem::Dependency
|
14
14
|
name: thor
|
@@ -142,7 +142,7 @@ required_rubygems_version: !ruby/object:Gem::Requirement
|
|
142
142
|
- !ruby/object:Gem::Version
|
143
143
|
version: '0'
|
144
144
|
requirements: []
|
145
|
-
rubygems_version: 3.1.
|
145
|
+
rubygems_version: 3.1.3
|
146
146
|
signing_key:
|
147
147
|
specification_version: 4
|
148
148
|
summary: Language-agnostic revision management tool
|