Add artifact type to source status API

docs/spec/v1alpha1/common.md

@@ -4,6 +4,34 @@ Common defines resources used across types.
 
 ## Specification
 
+### Source status
+
+Source objects should contain a status sub-resource that embeds an artifact object:
+
+```go
+// Artifact represents the output of a source synchronisation
+type Artifact struct {
+	// Path is the local file path of this artifact.
+	// +required
+	Path string `json:"path"`
+
+	// URL is the HTTP address of this artifact.
+	// +required
+	URL string `json:"url"`
+
+	// Revision is a human readable identifier traceable in the origin source system.
+	// It can be a commit sha, git tag, a helm index timestamp,
+	// a helm chart version, a checksum, etc.
+	// +optional
+	Revision string `json:"revision"`
+
+	// LastUpdateTime is the timestamp corresponding to the last
+	// update of this artifact.
+	// +required
+	LastUpdateTime metav1.Time `json:"lastUpdateTime,omitempty"`
+}
+```
+
 ### Source condition
 
 > **Note:** to be replaced with <https://github.com/kubernetes/enhancements/pull/1624>
@@ -52,7 +80,7 @@ const (
 const (
 	// InitializingReason represents the fact that a given source is being initialized.
 	InitializingReason string = "Initializing"
-    // URLInvalidReason represents the fact that a given source has an invalid URL.
+	// URLInvalidReason represents the fact that a given source has an invalid URL.
 	URLInvalidReason string = "URLInvalid"
 	// StorageOperationFailedReason signals a failure caused by a storage operation.
 	StorageOperationFailedReason string = "StorageOperationFailed"

docs/spec/v1alpha1/gitrepositories.md

@@ -57,14 +57,13 @@ type GitRepositoryStatus struct {
 	// +optional
 	Conditions []SourceCondition `json:"conditions,omitempty"`
 
-	// LastUpdateTime is the timestamp corresponding to the last status
+	// URL is the download link for the artifact output of the last repository sync.
-	// change of this repository.
 	// +optional
-	LastUpdateTime *metav1.Time `json:"lastUpdateTime,omitempty"`
+	URL string `json:"url,omitempty"`
 
-	// Path to the artifact output of the last repository sync.
+	// Artifact represents the output of the last successful repository sync.
 	// +optional
-	Artifact string `json:"artifacts,omitempty"`
+	Artifact *Artifact `json:"artifact,omitempty"`
 }
 ```
 
@@ -83,7 +82,7 @@ const (
 
 ## Spec examples
 
-Public Git repository:
+Pull the master of a public repository every minute:
 
 ```yaml
 apiVersion: source.fluxcd.io/v1alpha1
@@ -99,8 +98,52 @@ spec:
   url: https://github.com/stefanprodan/podinfo
   ref:
     branch: master
-    tag: "3.2.0"
+```
-    semver: ">= 3.2.0 <3.3.0"
+
+Checkout a specific commit from a branch:
+
+```yaml
+apiVersion: source.fluxcd.io/v1alpha1
+kind: GitRepository
+metadata:
+  name: podinfo
+  namespace: default
+spec:
+  interval: 1m
+  url: https://github.com/stefanprodan/podinfo
+  ref:
+    branch: master
+    commit: 363a6a8fe6a7f13e05d34c163b0ef02a777da20a
+```
+
+Pull a specific tag:
+
+```yaml
+apiVersion: source.fluxcd.io/v1alpha1
+kind: GitRepository
+metadata:
+  name: podinfo
+  namespace: default
+spec:
+  interval: 1m
+  url: https://github.com/stefanprodan/podinfo
+  ref:
+    tag: 3.2.0
+```
+
+Pull tag based on semver expression:
+
+```yaml
+apiVersion: source.fluxcd.io/v1alpha1
+kind: GitRepository
+metadata:
+  name: podinfo
+  namespace: default
+spec:
+  interval: 1m
+  url: https://github.com/stefanprodan/podinfo
+  ref:
+    semver: ">=3.1.0-rc.1 <3.2.0"
 ```
 
 HTTPS authentication (requires a secret with `username` and `password` fields):
@@ -136,7 +179,7 @@ metadata:
   name: podinfo
   namespace: default
 spec:
-  url: ssh://git@github.com:stefanprodan/podinfo
+  url: ssh://git@github.com/stefanprodan/podinfo
   secretRef:
     name: ssh-credentials
 ---
@@ -170,15 +213,19 @@ Successful sync:
 
 ```yaml
 status:
-  artifacts: http://source-controller.source-system/repositories/podinfo-default/5e747d3e088cd7a34ace4abc8cf7f3c3696e402f.tar.gz
+  artifact:
+    lastUpdateTime: "2020-04-07T06:59:23Z"
+    path: /data/gitrepository/podinfo-default/363a6a8fe6a7f13e05d34c163b0ef02a777da20a.tar.gz
+    revision: master/363a6a8fe6a7f13e05d34c163b0ef02a777da20a
+    url: http://<host>/gitrepository/podinfo-default/363a6a8fe6a7f13e05d34c163b0ef02a777da20a.tar.gz
   conditions:
   - lastTransitionTime: "2020-04-07T06:59:23Z"
     message: 'Fetched artifacts are available at
-      /data/repositories/podinfo-default/5e747d3e088cd7a34ace4abc8cf7f3c3696e402f.tar.gz'
+      /data/gitrepository/podinfo-default/363a6a8fe6a7f13e05d34c163b0ef02a777da20a.tar.gz'
     reason: GitOperationSucceed
     status: "True"
     type: Ready
-  lastUpdateTime: "2020-04-07T06:59:23Z"
+  url: http://<host>/gitrepository/podinfo-default/latest.tar.gz
 ```
 
 Failed sync:

docs/spec/v1alpha1/helmrepositories.md

@@ -29,19 +29,18 @@ type HelmRepositorySpec struct {
 #### Helm repository status
 
 ```go
-// HelmRepositoryStatus defines the observed state of the HelmRepository.
+// HelmRepositoryStatus defines the observed state of HelmRepository
 type HelmRepositoryStatus struct {
 	// +optional
 	Conditions []SourceCondition `json:"conditions,omitempty"`
 
-	// LastUpdateTime is the timestamp corresponding to the last status
+	// URL is the download link for the last index fetched.
-	// change of this Helm repository.
 	// +optional
-	LastUpdateTime *metav1.Time `json:"lastUpdateTime,omitempty"`
+	URL string `json:"url,omitempty"`
 
-	// URI for the artifact of the last successful repository index.
+	// Artifact represents the output of the last successful repository sync.
 	// +optional
-	Artifact string `json:"artifact,omitempty"`
+	Artifact *Artifact `json:"artifact,omitempty"`
 }
 ```
 
@@ -88,18 +87,17 @@ type HelmChartSpec struct {
 
 ```go
 // HelmChartStatus defines the observed state of the HelmChart.
-type HelmChartStatus struct {
+type HelmRepositoryStatus struct {
 	// +optional
 	Conditions []SourceCondition `json:"conditions,omitempty"`
 
-	// LastUpdateTime is the timestamp corresponding to the last status
+	// URL is the download link for the last chart fetched.
-	// change of this Helm chart.
 	// +optional
-	LastUpdateTime *metav1.Time `json:"lastUpdateTime,omitempty"`
+	URL string `json:"url,omitempty"`
 
-	// URI for the artifact of the latest successful Helm chart pull.
+	// Artifact represents the output of the last successful sync.
 	// +optional
-	Artifact string `json:"artifact,omitempty"`
+	Artifact *Artifact `json:"artifact,omitempty"`
 }
 ```
 
@@ -224,14 +222,13 @@ Successful indexation:
 
 ```yaml
 status:
-  artifact: http://<host>/helmrepositories/podinfo-default/index-21c195d78e699e4b656e2885887d019627838993.yaml
+  url: http://<host>/helmrepository/podinfo-default/index.yaml
   conditions:
     - lastTransitionTime: "2020-04-10T09:34:45Z"
       message: Fetched artifact are available at /data/helmrepositories/podinfo-default/index-21c195d78e699e4b656e2885887d019627838993.yaml
       reason: IndexationSucceeded
       status: "True"
       type: Ready
-  lastUpdateTime: "2020-04-10T09:34:45Z"
 ```
 
 Failed indexation:
@@ -264,14 +261,13 @@ Successful chart pull:
 
 ```yaml
 status:
-  artifact: http://<host>/helmcharts/redis-default/redis-10.5.7.tgz
+  url: http://<host>/helmcharts/redis-default/redis-10.5.7.tgz
   conditions:
     - lastTransitionTime: "2020-04-10T09:34:45Z"
       message: Fetched artifact are available at /data/helmcharts/redis-default/redis-10.5.7.tgz
       reason: ChartPullSucceeded
       status: "True"
       type: Ready
-  lastUpdateTime: "2020-04-10T09:34:45Z"
 ```
 
 Failed chart pull: