Adding content

README.md

@@ -15,7 +15,29 @@ and to use the information for activities such as:
 
 * build
 * deploy
-* discover APIs definitions
+* discover OpenAPI definitions
+
+## What does it do
+
+The **.well-known/devops.json** specification removes devops process 
+assumptions, such as script locations. It also provides a location
+to store application reference links such a OpenAPI definitions.
+All this with the code on Git / source version control.
+
+You may already have a devops toolchain for build and deploy but many require
+you to enter the Git details into them.  By having a **devops** definition as
+described here you can further automate the process - and have a roadmap
+to change tooling if circumstances change.
+
+If you do not include the **.well-known/devops.json** file creation into 
+your Git repository creation process, maybe some of the concepts may 
+provoke some improvements into your current process.
+
+## What doesn't it do
+
+The **devops** definition does not replace your existing tools or processes.
+
+
 
 ## Background
 
@@ -23,8 +45,14 @@ A common approach organisations have is to create well known, at least within th
 file names within Git repositories and then configure tools to access those files for their configuration 
 and execution.
 
-The proposal here is to define one DevOps file location and the content within to provide location information
+These well known organisation files tend to reside in the root directory
-for other files or actions to perform.
+or some well known directory such as "tools" or "build".  As you include 
+more tools and processes the number of these files grow in the root
+directory.
+
+The proposal here is to define one DevOps file location and the content 
+within to provide location information for other files or actions to 
+perform.
 
 ## Specification 
 
@@ -58,3 +86,15 @@ If your organisation already has standard automation tools and pipeline process,
 and the specifications that useful.  If the specification is not relevant in its entirety, maybe you find the
 concept or portions useful for adaptation in your organisation.
 
+## SBOM
+
+With increased attention on software supply chains and the need to 
+create and update the software bill of materials (SBOM), the 
+proposed definition is flexible to linking to SBOM tools if required.
+
+Your existing tooling may already cater for SBOM creation so please
+check.  If your existing tools do cover SBOM then you could link
+the results to the **devops.json** definition so that it is 
+closer to the source.
+
+See the link for more information on [SBOM](guide/sbom.md)

guide/build.md

@@ -2,8 +2,44 @@
 
 The **build** section of the **devops.json** is used to build the component.
 
-The build action can be 
+The build action would include the location of any build scripts or 
+configuration files. Like all sections, there is guide reference which can give further information on how the section can be used within your
+environment.
 
-Like all sections, there is guide reference which can give further information
+If you are using common build pipelines in your CI/CD then 
-on how the section can be used.
+the linked URL might be
 
+* An azure-pipelines.yml as used in Azure Devops
+* A declarative Jenkinsfile used by Jenkins/Hudson
+
+
+
+## Azure pipelines
+
+A sample definition for Azure pipelines is:
+
+```json
+    "build": [
+        {
+            "engine": {
+                "category": "BUILD",
+                "name": "AZURE PIPELINE"
+            },
+            "config": "build/pipelines/azure-pipelines.yml",
+        }
+    ],
+```
+
+If the Git is hosted on Azure and you want to use Azure pipelines, you
+need to create the above file in the root Git directory with the relevant
+details. ( You can also specify a different location. )
+
+You can create a pipeline using the command:
+
+```
+az pipelines create -name "Default" --description "Generated pipeline" -- folder-path "build/pipelines" --repository-type tfsgit --skip-run true
+```
+
+All of this can be done using a simple Powershell script based on the
+**devops** definition and can be executed at the time of creating the 
+definition.

guide/sbom.md

@@ -0,0 +1,3 @@
+# Software Bill of Materials (SBOM)
+
+

specification/rediops.json

@@ -64,7 +64,7 @@
         },
         "/devops/{id}": {
             "summary": "Operate on the identified resources",
-            "description": "This service and its operations are intended for use where \nthe DevOps information from source control versioning (e.g. Git)\nis wanted to be stored on a centrral registry.\n\nThe process of updating the central registry can be automated by use\nof web hooks which will retrieve the latest **.well-known/deveops.json**\nfrom Git on commits as an example.\n\nThis definition is only applicable if the **deveops** is\npublished as a service outside of the source code.",
+            "description": "This service and its operations are intended for use where \nthe DevOps information from source versioning (e.g. Git)\nis wanted to be stored on a centrral registry.\n\nThe process of updating the central registry can be automated by use\nof web hooks which will retrieve the latest **.well-known/deveops.json**\nfrom Git on commits as an example.\n\nThis definition is only applicable if the **deveops** is\npublished as a service outside of the source code.",
             "get": {
                 "tags": [
                     "Proposed"
@@ -747,7 +747,7 @@
                     },
                     "source": {
                         "$ref": "#/components/schemas/engine-model",
-                        "description": "Source control version engine.\n\nThis can be used by tools to retreive source code using binary executables.\n\nSome common tools are \"Git\", \"TFS\", \"Mercurial\", \"CVS\".",
+                        "description": "Source version control system engine.\n\nThis can be used by tools to retreive source code using binary executables.\n\nSome common tools are \"Git\", \"TFS\", \"Mercurial\", \"CVS\".",
                         "example": "Git"
                     }
                 },