doc: fixed contribution page
Change-Id: I6b07b70d4430ce9498c531d657c5d42cdbac33c8
diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md
index 7c02144..c14c332 100644
--- a/CONTRIBUTING.md
+++ b/CONTRIBUTING.md
@@ -21,7 +21,7 @@
All submissions, including submissions by project members, require review. We
use Gerrit code reviews at https://cue-review.googlesource.com for this purpose.
-Please read the [Contributing Guide][./doc/contribute.md]
+Please read the [Contributing Guide](./doc/contribute.html)
before reading patches.
## Community Guidelines
diff --git a/README.md b/README.md
index 32a67ec..88ca937 100644
--- a/README.md
+++ b/README.md
@@ -81,7 +81,7 @@
Our canonical Git repository is located at https://cue.googlesource.com.
-To contribute, please read the [Contribution Guide](./doc/contribute.md).
+To contribute, please read the [Contribution Guide](./doc/contribute.html).
##### Note that we do not accept pull requests and that we use the issue tracker for bug reports and proposals only.
diff --git a/doc/contribute.md b/doc/contribute.html
similarity index 95%
rename from doc/contribute.md
rename to doc/contribute.html
index 33806b9..40f7392 100644
--- a/doc/contribute.md
+++ b/doc/contribute.html
@@ -1,4 +1,38 @@
-# Contribution Guide
+
+<!DOCTYPE html>
+<html>
+<head>
+<meta http-equiv="Content-Type" content="text/html; charset=utf-8">
+<meta name="viewport" content="width=device-width, initial-scale=1">
+<meta name="theme-color" content="#375EAB">
+
+ <title>Contribution Guide - The CUE Configuration Language</title>
+
+<link type="text/css" rel="stylesheet" href="https://golang.org/lib/godoc/style.css">
+
+<link rel="stylesheet" href="/lib/godoc/jquery.treeview.css">
+
+</head>
+<body>
+
+<div id='lowframe' style="position: fixed; bottom: 0; left: 0; height: 0; width: 100%; border-top: thin solid grey; background-color: white; overflow: auto;">
+...
+</div><!-- #lowframe -->
+
+<div id="topbar" class="wide"><div class="container">
+<div class="top-heading" id="heading-wide"><a href="/">The CUE Configuration Language</a></div>
+</div></div>
+
+<div id="page" class="wide">
+<div class="container">
+
+ <h1>
+ Contribution Guide
+ <span class="text-muted"></span>
+ </h1>
+
+<div id="nav"></div>
+
<p>
The CUE project welcomes all contributors.
@@ -729,16 +763,18 @@
Only trivial or cosmetic changes will be accepted without an associated issue.
</li>
+<!-- TODO
<li>
Change sent during the freeze phase of the development cycle, when the tree
is closed for general changes.
In this case,
-a maintainer might review the code with a line such as <code>R=go1.12</code>,
+a maintainer might review the code with a line such as <code>R=cue1.1</code>,
which means that it will be reviewed later when the tree opens for a new
development window.
-You can add <code>R=go1.XX</code> as a comment yourself
+You can add <code>R=cue1.XX</code> as a comment yourself
if you know that it's not the correct time frame for the change.
</li>
+-->
</ul>
<!--
@@ -1151,3 +1187,18 @@
Make sure to explicitly specify <code>HEAD</code>, which is usually not required when sending
single changes.
</p>
+
+
+<div id="footer">
+Except as <a href="https://developers.google.com/site-policies#restrictions">noted</a>,
+the content of this page is licensed under the
+Creative Commons Attribution 3.0 License,
+and code is licensed under a <a href="/LICENSE">Apache 2 license</a>.<br>
+<a href="http://www.google.com/intl/en/policies/privacy/">Privacy Policy</a>
+</div>
+
+</div><!-- .container -->
+</div><!-- #page -->
+
+</body>
+</html>
diff --git a/doc/tutorial/kubernetes/README.md b/doc/tutorial/kubernetes/README.md
index c02f143..0dd9789 100644
--- a/doc/tutorial/kubernetes/README.md
+++ b/doc/tutorial/kubernetes/README.md
@@ -894,8 +894,8 @@
If more than one instance is selected the `cue` tool may either operate
on them one by one or merge them.
The default is to merge them.
-Different instances of a package are typically not compatible: as instances
-in different subdirectories may have different specializations.
+Different instances of a package are typically not compatible:
+different subdirectories may have different specializations.
A merge pre-expands templates of each instance and then merges their root
values.
The result may contain conflicts, such as our top-level `_component` field,
@@ -1015,7 +1015,7 @@
In Section "Quick 'n Dirty" we showed how to quickly get going with CUE.
With a bit more deliberation, one can reduce configurations even further.
-Also, we would like to define a configuration that more generic and less tied
+Also, we would like to define a configuration that is more generic and less tied
to Kubernetes.
We will rely heavily on CUEs order independence, which makes it easy to
@@ -1023,12 +1023,7 @@
This makes it easy, for instance, to put frequently used fields in one file
and more esoteric one in another and then combine them without fear that one
will override the other.
-
-For our manually constructed configuration we use this concept by defining
-a more generic and abstract model for the commonly used Kubernetes features
-while leaving the
-We define mappings to map the common configuration to Kubernetes and then
-merge them with the Kubernetes fields that were included verbatim.
+We will take this approach in this section.
The end result of this tutorial is in the `manual` directory.
In the next sections we will show how to get there.
@@ -1073,49 +1068,27 @@
deployment <Name>: {
name: Name | string
- ...
+ ...
}
```
A Kubernetes-specific file then contains the definitions to
convert the generic objects to Kubernetes.
-```
-// file k8s.cue
-package cloud
-
-// kubernetes holds the Kubernetes versions of definitions.
-kubernetes services: {
- "\(k)": v.kubernetes & {
- apiVersion: "v1"
- kind: "Service"
-
- metadata name: x.name
- metadata labels: x.label
- spec selector: x.label
-
- spec ports: [ p for p in x.port ]
- } for k, v in service
-}
-...
-```
-
-This approach allows us to come up with simple cloud definitions, while
-still have an out to use any Kubernetes-specific option we may want.
-
Overall, the code modeling our services and the code generating the kubernetes
code is separated, while still allowing to inject Kubernetes-specific
data into our general model.
At the same time, we can add additional information to our model without
it ending up in the Kubernetes defintions causing it to barf.
+
### Deployment Definition
For our design we assume that all Kubernetes Pod derivatives only define one
container.
This is clearly not the case in general, but often it does and it is good
practice.
-Conveniently, it simplifies this example.
+Conveniently, it simplifies our model as well.
We base the model loosely on the master templates we derived in
Section "Quick 'n Dirty".
@@ -1125,7 +1098,6 @@
```
deployment <Name>: _base & {
name: Name | string
- kind: "deployment" | "stateful" | "daemon"
...
```
@@ -1134,8 +1106,6 @@
This also eliminates the need for `_spec`.
The next step is to pull common fields, such as `image` to the top level.
-We introduce maps for arguments, environment variables, ports, and volumes
-to simplify their definition.
Arguments can be specied as a map.
```
@@ -1157,7 +1127,7 @@
Both maps get defined in the container definition, but only `port` gets
included in the service definition.
This may not be the best model, and does not support all features,
-but it shows how one can chose a very different representation.
+but it shows how one can chose a different representation.
A similar story holds for environment variables.
In most cases mapping strings to string suffices.
@@ -1187,7 +1157,7 @@
}
```
-All other fields that may way want to define can go into a generic kubernetes
+All other fields that we way want to define can go into a generic kubernetes
struct that gets merged in with all other generated kubernetes data.
```
@@ -1227,7 +1197,7 @@
Running our usual count yields
```
find . | grep kube.cue | xargs wc | tail -1
- 536 1155 11398 total
+ 542 1190 11520 total
```
This does not count our conversion templates.
Assuming that the top-level templates are reusable, and if we don't count them
@@ -1237,7 +1207,7 @@
### Conclusions Manual Configuration
-We have shown that we can further compact our configuration by manually
+We have shown that we can further compact a configuration by manually
optimizing template files.
However, we have also shown that the manual optimizition only gives
a marginal benefit with respect to the quick-and-dirty semi-automatic reduction.
@@ -1246,14 +1216,13 @@
Manually tailoring your configurations allows creating an abstraction layer
between logical definitions and Kubernetes-specific definitions.
-At the same time, CUE's flexibility,
-resulting from its order independences,
+At the same time, CUE's order independence
makes it easy to mix in low-level Kubernetes configuration whereever it is
convenient and applicable.
Manual tailoring also allows us to add our own definitions without breaking
-Kuberenetes.
-This is crucial in defining information relevant to your definitions,
+Kubernetes.
+This is crucial in defining information relevant to definitions,
but unrelated to Kubernetes, where they belong.
Separating abstract from concrete configuration also allows us to create
