revision 1.5.0 → 1.5.2
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- 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
|