-
Notifications
You must be signed in to change notification settings - Fork 0
/
Copy pathapproach_and_implementation.html
125 lines (125 loc) · 5.22 KB
/
approach_and_implementation.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
<!DOCTYPE html>
<html lang="en-US">
<head>
<title>CMTools</title>
<link rel="stylesheet" href="/css/site.css">
</head>
<body>
<nav>
<ul>
<li><a href="/">Home</a></li>
<li><a href="index.html">README</a></li>
<li><a href="LICENSE">LICENSE</a></li>
<li><a href="INSTALL.html">INSTALL</a></li>
<li><a href="user_manual.html">User Manual</a></li>
<li><a href="about.html">About</a></li>
<li><a href="search.html">Search</a></li>
<li><a href="https://github.com/caltechlibrary/CMTools">GitHub</a></li>
</ul>
</nav>
<section>
<h1 id="why-codemeta-tools">Why CodeMeta Tools?</h1>
<p>Over the last several years I’ve folded in the codemeta.json file as
a data source for building and releasing software for Caltech Library.
Initially I used a tool I wrote called “codemeta2cff”. It did one thing
which was create a CITATION.cff from the codemeta.json file. Over time I
wound up reusing the CodeMeta to generate version files for Go, Python,
JavaScript and TypeScript projects. I wound up generating the “about.md”
file from CodeMeta content too. The evolution was organic and resulted
in a series of scripts, Makefile rules and Pandoc templates. CodeMeta
Tools is a consolidation of that evolution into a single simple tool. It
also integrated other data like Git repository hash and compile dates.
You can now use a single tool to generate your CITATION.cff, about.md
and version files with a single tool. This streamlines the setup of
projects as well as maintain these various files from a single source of
truth held in the codemeta.json file.</p>
<p>So why is this significant? The metadata held in our CodeMeta JSON
file is very helpful when integrating into software repositories like <a
href="https://data.caltech.edu">CaltechDATA</a>. While my initial focus
in adopting CodeMeta was documentation for my projects I think it can
play a common role across projects regardless of implementation
language. On the command line this means you can easily have a
consistent “version” response indicating not just the semver and program
name but also the Git hash and compile date. This is important for
support reasons. As we evolve programs that are deployed on individual
computers users often don’t update their software. Knowing that they are
running a different version than the currently supported one can cut
down the time needed to diagnosis issues. Similarly if we introduce a
regression in a new version we can check to see if the fix got applied
because the Git hash in the version string will change on each commit.
For server software having consistent version info serves a similar
role.</p>
<h1 id="what-problem-are-we-solving-with-cm-tools">What problem are we
solving with CM Tools?</h1>
<p>The following files are common in my projects and other’s projects at
Caltech Library.</p>
<ul>
<li>CITATION.cff</li>
<li>about.md</li>
<li>version.go, version.py, version.js, version.ts</li>
<li>page templates for the project website</li>
</ul>
<p>Having a CM Tool that can generate these means the build processes
can be simplified and can more easily translate across the POSIX and
Windows divide.</p>
<p>The common files that can use the information in the CodeMeta file
are likely to grow over time. The implementation of CM Tools should make
it easy to add additional transformations as needed.</p>
<p>Right now my build processes require Pandoc. Pandoc isn’t something
that most developers think about as part of their build tool chain
outside of building websites. With an easy to install command line tool
the Pandoc dependency can be removed.</p>
<h1 id="implementation">Implementation</h1>
<p>CM Tools is implemented as a <a
href="https://typescriptlang.org">TypeScript</a> program compiled using
<a href="https://deno.com">Deno</a>. The <code>cmt</code> is a “static
binary”[^1] that can be “installed” with a simple copy command.
TypeScript was chosen because it is a superset of JavaScript which is
one of the most common programming languages in the early 21st century.
This is the type of tool that will benefit from community contributions.
Deno provide easy cross platform compilation for our supported operating
systems – macOS, Windows and Linux. Deno and TypeScript together provide
many of the advantages of our Go based utilities with the advantage of a
large part of the Library, Archives and Museum developer communities
that could potentially contribute.</p>
<p>The architecture of CM Tools is a series of small TypeScript
files</p>
<dl>
<dt>codemeta.ts</dt>
<dd>
provides the basic CodeMeta 3 object.
</dd>
<dt>gitcmds.ts</dt>
<dd>
provides a thin wrapper around the Git command for retrieving Git hash
values
</dd>
<dt>helptext.ts</dt>
<dd>
provides the help documentation use to generate man pages and website
doc pages
</dd>
<dt>version.ts</dt>
<dd>
This is generated by CM Tools’ <code>cmt</code> command and holds the
version info for CM Tools
</dd>
<dt>person_or_organization.ts</dt>
<dd>
This holds the agent model for people and organizations used in the
CodeMeta object
</dd>
<dt>transform.ts</dt>
<dd>
This does the heavy lifting and transforming the CodeMeta 3 object into
our target files.
</dd>
<dt>cmt.ts</dt>
<dd>
This is the TypeScript that provides our command line interface for CM
Tools
</dd>
</dl>
</section>
</body>
</html>