-
Notifications
You must be signed in to change notification settings - Fork 1
/
Copy pathindex.html
229 lines (208 loc) · 10.1 KB
/
index.html
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
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
94
95
96
97
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
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
<!DOCTYPE html>
<html lang="en" dir="ltr">
<!-- Notes to editors:
* Set tabs to 2 spaces.
* Never use tab characters.
* Remove all trailing white-space from lines.
* Some vertical white-space is good, too much is bad.
* Paragraphs should have one sentance per line!
* Use TODO's very sparingly and always include a link to the relevant issue(s)
or project task(s).
-->
<head>
<meta charset="utf-8"/>
<meta name="viewport" content="width=device-width, initial-scale=1.0, maximum-scale=1.0, minimum-scale=1.0"/>
<meta name="author" content="Joseph W Donahue" />
<meta name="description" content="Version Meta spec and web site" />
<meta http-equiv="Refresh" content="0;URL=https://versionmeta.org/" />
<link rel="canonical" href="https://versionmeta.org/" />
<title>Version Meta Experimental.0 {VSChemaUnderDef.0}</title>
</head>
<body>
<!-- TODO: CSS! -->
<div id="product-tag">
<h1>Version Meta</h1>
<div id="version-tag">
Version: Experimental.0 {VSchemaInDev.0}
</div>
</div>
<h2 id="summary">
Summary
</h2>
<p>
Version Meta is a proposed standard tag for version strings.
The tag is meant to convey both; human and machine readable information, regarding the location of the version schema used to build the version string.
All version meta tags will be enclosed in curly braces {} and MUST always immediately precede or follow a version string conforming to the specified schema.
See <a href=http://versionschema.org>versionschema.org</a> for details on the proposed schema DOM.
The version listed near the top of this page is an example of a well-known schema tag, that tooling can use to lookup the named schema (service location is TBD).
</p>
<h2 id="introduction">
Introduction
</h2>
<p>
There are many packaging schemes in use today that each;
either have their own versioning scheme,
or varying levels of adherence to some specified standard,
such as one version or another of <a href="https://semver.org">Semantic Versioning</a>.
Currently only context and format analysis distinguishes them from each other.
Consider the following version strings:
</p>
<ol>
<li>"1"</li>
<li>"1.0"</li>
<li>"1.0.0"</li>
<li>"1.0.0.0"</li>
</ol>
<p>
Depending on the context,
#1 might just be an abbreviation referring to any of the others.
#2 could also be an abbreviation of #'s 3 or 4,
but its format could also imply that it is a tuple version number of some unknown pedigree.
#3 may be the most pernicious,
as it appears that it may conform to any of SemVer's specification versions,
and the version triple is probably the most common format in use,
so one cannot assume it's a SemVer string based on the triple.
#4 could be almost anything.
None of them tell us anything about the logic,
if any,
that was applied to generate the version.
</p>
<p>
Most versioning schemes give us some relief in the form of meta tags,
such as prerelease labels or build meta-data.
If we understand the language that the tags derive from,
we can make some assumptions about the relative quality of each version of a particular product.
<!-- Need a more relevent example here -->
Only rarely can we apply such logic to different products satisfying similar needs,
because we know nothing of the processes applied by the varying product developers.
Consider the following:
</p>
<ul>
<li>UberSkyLib 2.1.3-RC1</li>
<li>HyperSkyLib 0.0.93-Experimental</li>
</ul>
<p>
One might suspect that the UberSkyLib product is a stable,
shipping product and HyperSkyLib is obviously experimental,
so perhaps we should investigate UberSkyLib as a candidate for inclusion in our product?
Other than the implied goodness of the RC1 tag,
and the fact there are no leading zeroes in the version number,
we really have no reason at all to suspect that UberSkyLib is any more stable than HyperSkyLib.
Even if we know they both adhere to <a href="https://semver.org">Semantic Versioning</a>,
we still don't know anything about their relative development practices.
Without digging into both of them using ad-hoc research methods,
all we can do is guess.
It could be that HyperSkyLib is based off of UberSkyLib 1.0.0 and that their 93 versions are a couple of hundred fewer than UberSkyLib.
The standards and methods of each product team cannot be known from the version label,
and the contexts within which version labels are found;
rarely have obvious linkage to those standards and methods.
</p>
<p>
The proposed solution to these and other issues around package version labels,
is to promote the use of the Version Meta tag,
to provide a standard method for obtaining the necessary information we need,
to make critical judgements regarding the expected quality of a given release.
I propose that a <a href="http://versionschema.org">Version Schema</a> standard be developed
and evolve to satisfy the needs of the developer and consumer communities.
The Version Meta standard will only address the content,
formats and locations of the Version Meta tag,
not the Version Schema.
</p>
<div id="spec">
<div id="versionmeta">
<h2 id="version_meta_specification">
Version Meta Specification (VersionMeta)</h2>
<p>
The key-words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", "SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY", and "OPTIONAL" in this document are to be interpreted as described in <a href="http://tools.ietf.org/html/rfc2119">RFC 2119</a>.
The phrase "Version Meta tag" used herein,
refers to tags used to specify a URI to a Version Schema ({https://schemas.versionschema.org/SimpleCounter.xml}),
or a well-known identifier ({SimpleCounter}),
and should not be confused with other meta tags,
that may be specified by various version schemes (Build Meta used in SemVer for instance).
</p>
<p><a name="1"><a href="#1">1.</a></a>
All version Meta tags MUST be expressed as UTF-8 code sequences.
</p>
<p><a name="2"><a href="#2">2.</a></a>
All Version Meta tags MUST begin with an opening curly brace '{',
which MUST be followed by a URI,
which MUST be followed by a closing curly brace '}'.
</p>
<p>TBD: Right to left languages?</p>
<p>TBD: Different/Alternate delimiters?</p>
<p><a name="3"><a href="#3">3.</a></a>
Version Meta tags MUST NOT contain any whitespace,
between the URI or well-known identifier,
and the opening and closing currly braces.
</p>
<p><a name="4"><a href="#4">4.</a></a>
There MUST NOT be more than one Version Meta tag associated with any version string.
</p>
<p><a name="5"><a href="#5">5.</a></a>
Version Meta tags SHOULD be placed on the same line as their respective version strings.
</p>
<p><a name="6"><a href="#6">6.</a></a>
Version Meta tags SHOULD follow their respective version strings.
</p>
<p><a name="7"><a href="#7">7.</a></a>
Version Meta tags MUST be within plus or minus one line of their respective version strings.
</p>
<p><a name="8"><a href="#8">8.</a></a>
Version Meta tags MAY precede or follow their respective version strings.
</p>
<p><a name="9"><a href="#9">9.</a></a>
When multiple product version strings are displayed in close proximity,
such as a list or table,
the associated Version Meta tags MUST be displayed with a consistent relative position to their respective version strings.
</p>
<p><a name="10"><a href="#10">10.</a></a>
All Version Meta tags MUST resolve to a Version Schema as defined by
<a href="http://versionschema.org">versionschema.org.</a>
</p>
<p><a name="#n">n.</a>
</p>
<h2 id="why-use-version-meta">Why Use Version Meta?</h2>
<p>
Because you want your customers to understand your versioning scheme.
When your customers don't grok your release versioning policies,
you burn a lot of customer support cycles and so do they.
Because you are proud of your processes and confident it will benefit both you and your customers.
</p>
<p>
Widespread adoption of Version Meta tags,
will allow automation to properly reason over dependency graphs and pull required updates with less risk to your software development projects.
It allows flexibility in processes,
avoiding the use of lowest common demonitor standards.
It's the next step from Semantic Versioning,
on the road out of dependency hell.
</p>
<h2 id="about">About</h2>
<p>
The Version Meta specification is originally authored by me,
<a href="https://www.linkedin.com/in/joseph-donahue-43b4b790/">Joseph W Donahue</a>.
I am looking forward to collaborating with anyone who has a contribution to make to this effort.
</p>
</div>
</div>
<h2 id="license">License</h2>
<p>
This document is <a href=LICENSE>licensed, as-per the LICENSE file,</a>
as derived from the <a href="https://opensource.org/licenses/MIT">MIT License</a>.
The original condition:
<p>
"The above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software"
</p>
<p>
was changed to:
</p>
<p>
"The above copyright notice,
<b>a clear indication whether the content has been modified</b>,
and this permission notice shall be included in all copies or substantial portions of the Software".
</p>
In other words, MIT + tell everyone whether you simply copied the content or modified it.
</p>
<p><small>Contact: [email protected]</small></p>
<p><small>Last updated 2020-02-05 11:00 UTC</small></p>
</body>
</html>