Skip to content

Commit c913cc2

Browse files
author
Michael Haberler
committed
infra: a first stab at repos & flows descriptions
1 parent 701a614 commit c913cc2

File tree

2 files changed

+170
-2
lines changed

2 files changed

+170
-2
lines changed

‎_data/docs.yml

+7-2
Original file line numberDiff line numberDiff line change
@@ -3,7 +3,7 @@
33
- site/about-this-site
44
- index-getting-started
55
- index-user
6-
- index-HAL
6+
- index-HAL
77
- getting-help
88

99
- title: Developing
@@ -13,9 +13,14 @@
1313
- index-documenting
1414
- developing/develop-index
1515
- developing/qtquickvcp
16-
16+
1717
- title: Manpages
1818
docs:
1919
- man/man1
2020
- man/man3
2121
- man/man9
22+
23+
- title: Project Infrastructure
24+
docs:
25+
- infra/repositories
26+

‎docs/infra/repositories.asciidoc

+163
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,163 @@
1+
---
2+
---
3+
4+
:skip-front-matter:
5+
:imagesoutdir: docs/infra/repositories
6+
7+
:toc:
8+
= git repos & automated build flows
9+
10+
There are quite a few
11+
https://github.com/machinekit[Machinekit git repositories].
12+
Here is what is contained where, and how they fit together with the build process.
13+
14+
15+
== https://github.com/machinekit/machinekit[main machinekit repo]
16+
17+
- all the source code for HAL, RT, the CNC stack, and user interfaces lives here.
18+
- package builds happen from here using the https://travis-ci.org/[Travis CI service], driven https://github.com/machinekit/machinekit/tree/master/.travis[from this directory]
19+
20+
=== Posting a pull request against the machinekit repo
21+
[seqdiag, "mk_pr_flow", "svg"]
22+
----
23+
seqdiag {
24+
// Do not show activity line
25+
activation = none;
26+
27+
// Change note color
28+
default_note_color = lightblue;
29+
30+
user -> github [label = "posts pull request"];
31+
github -> travis [label = "PR webhook", note = "build & \nrun regresstion tests"];
32+
github <- travis [label = "set commit status"];
33+
user <- github [label = "PR result visible"];
34+
}
35+
----
36+
37+
=== Merging a pull request into the machinekit repo
38+
[seqdiag, "mk_merge_flow", "svg",width=100%,height=100%]
39+
----
40+
seqdiag {
41+
// Do not show activity line
42+
activation = none;
43+
44+
// Change note color
45+
default_note_color = lightblue;
46+
47+
maintainer -> github [label = "merge PR"];
48+
github -> travis [label = "merge webhook", note = "build\npackages"];
49+
travis ->> deb.machinekit.io [label = "upload deb"];
50+
travis <- deb.machinekit.io [label = "successful upload", note = "new\npackage\nonline"];
51+
//deb.machinekit.io -> users [label = "apt-get <package>"];
52+
github <- travis [label = "set commit status"];
53+
maintainer <- github [label = "merge result visible"];
54+
}
55+
----
56+
57+
=== comp and instcomp manpage extraction
58+
This happens in the https://jenkins.machinekit.io/view/machinekit/job/machinekit-manpages/[manpage extarction job].
59+
[seqdiag, "mk_manpage_flow", "svg"]
60+
----
61+
seqdiag {
62+
// Do not show activity line
63+
activation = none;
64+
65+
// Change note color
66+
default_note_color = lightblue;
67+
68+
maintainer -> github [label = "merge PR"];
69+
github -> jenkins.machinekit.io [label = "merge webhook",
70+
note = "extract comp &\ninstcomp manpages\nstore on jenkins host\nuntil next\nwebsite build"];
71+
github <- jenkins.machinekit.io [label = "set commit status"];
72+
maintainer <- github [label = "manpage generation\nresult visible"];
73+
}
74+
----
75+
76+
77+
== https://github.com/machinekit/machinekit-docs[machinekit documentation]
78+
79+
* source for the website, http://asciidoctor.org[asciidoc] format as understood by asciidoctor.
80+
* all static documentation resides here.
81+
* artefacts from other repos (comp & instcomp manpages, protobuf docs) are imported during the build process:
82+
** manual pages for HAL components: see link:/docs/infra/repositories/#comp-and-instcomp-manpage-extraction[comp and instcomp manpage extraction]
83+
** protobuf files are http://preview.machinekit.io/docs/machinetalk/protobuf/[automatically converted for documentation] using https://github.com/mhaberler/protoc-gen-doc[protoc-gen-doc]
84+
85+
86+
=== Posting a pull request against the machinekit-docs repo
87+
Formatting happens in the https://jenkins.machinekit.io/view/machinekit/job/website-preview/[website preview job].
88+
The resulting HTML is uploaded to the https://github.com/machinekit-ci/machinekit-ci.github.io
89+
repo which serves the preview.machinekit.io domain.
90+
91+
There is only a single preview website; a followup PR overwrites the previous content of preview.machinekit.io.
92+
[seqdiag, "mkdocs_pr_flow", "svg"]
93+
----
94+
seqdiag {
95+
// Do not show activity line
96+
activation = none;
97+
98+
// Change note color
99+
default_note_color = lightblue;
100+
101+
user -> github [label = "posts pull request"];
102+
github -> jenkins.machinekit.io [label = "PR webhook",
103+
note = "import manpages\nformat protobuf\nformat website &\nupload HTML"];
104+
github <- jenkins.machinekit.io [label = "set commit status", note = "PR visible on\npreview.machinekit.io"];
105+
user <- github [label = "PR result visible"];
106+
}
107+
----
108+
109+
110+
=== Merging a pull request into the machinekit-docs repo
111+
Formatting happens in the https://jenkins.machinekit.io/view/machinekit/job/website-production/[website production job].
112+
The resulting HTML is uploaded to the https://github.com/machinekit/machinekit.github.io
113+
repo which serves the www.machinekit.io domain.
114+
115+
The linkchecker output is www.machinekit.io/linkchecker.html[available here].
116+
117+
[seqdiag, "mkdocs_merge_flow", "svg",width=100%,height=100%]
118+
----
119+
seqdiag {
120+
// Do not show activity line
121+
activation = none;
122+
123+
// Change note color
124+
default_note_color = lightblue;
125+
126+
maintainer -> github [label = "merge PR"];
127+
github -> jenkins.machinekit.io
128+
[label = "merge webhook",
129+
note = "import manpages\nformat protobuf\nformat website\nrun linkchecker\nupload HTML"];
130+
github <- jenkins.machinekit.io [label = "set commit status", note = "merge result visible on\nwww.machinekit.io"];
131+
maintainer <- github [label = "PR result visible"];
132+
}
133+
----
134+
135+
== https://github.com/machinekit/machinetalk-protobuf[Protobuf message definitions]
136+
137+
- these define the format of messages used in several places throughout machinekit, both internally and as an external API
138+
- for the format see the excellent https://developers.google.com/protocol-buffers/[Google Protobuf documentation].
139+
- note files in this repo are published under the https://github.com/machinekit/machinetalk-protobuf/blob/master/LICENSE[MIT license], other than https://github.com/machinekit/machinekit/blob/master/COPYING[machinekit which is mostly GPL2 and LGPL]. This means usage of the remote API is governed by the former, similar to the Linux kernel which is GPL but the using code can be pretty much any license.
140+
141+
142+
== https://github.com/machinekit/mksocfpga[FPGA firmware for SoC/FPGA platforms]
143+
- contains VHDL source and configurations for various platforms
144+
- firmware packages are built automatically if a PR is merged into this repo
145+
146+
== https://github.com/machinekit/pymachinetalk[Python machinetalk bindings]
147+
These serve as examples how to remotely interact with HAL and LinuxCNC stack.
148+
149+
== https://github.com/machinekit/machinekit-dkms[Any kernel modules required for Machinekit]
150+
Kernel modules and drivers are by definition kernel-dependent and therefore not part of the standard build.
151+
152+
Any drivers should be posted against this repo, following the example of the existing ones. A merge against this repo will cause the machinekit-dms package be build; if installed, this package will build any drivers _on the target platform against all installed kernel versions_.
153+
154+
== https://github.com/machinekit/machinekit.github.io[github.machinekit.io]
155+
156+
- static html content served by github for domain www.machinekit.io
157+
- fed from jenkins.machinekit.io via git push after sucessful format and linkcheck
158+
- see jenkins job https://jenkins.machinekit.io/view/machinekit/job/website-production/[website-production]
159+
160+
161+
162+
163+

0 commit comments

Comments
 (0)