Wardrobe
/
rediOps
mirror of https://github.com/meerkat-manor/rediOps.git
5
0
Fork 0
Code Issues Projects Releases Wiki Activity

Merge pull request #2 from meerkat-manor/documentation 

Documentation
main v0.0.5
meerkat-manor 2024-08-18 12:33:26 +10:00 committed by GitHub
parent 5124353244 d52bdaeb61
commit 6c7a1363c4
No known key found for this signature in database
GPG Key ID: B5690EEEBB952194
12 changed files with 1144 additions and 7 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

12
.vscode/settings.json vendored 100644
View File

@ -0,0 +1,12 @@
{
"cSpell.words": [
"cmdb",
"initialisation",
"Qaskx",
"rediops",
"synchronised"
],
"cSpell.ignoreWords": [
"apip"
]
}

9
background.md
View File

@ -1,9 +1,4 @@
# Background
_This document is under construction_
```mermaid
mindmaps
```

94
docs/analysis_start.md 100644
View File

@ -0,0 +1,94 @@
# Analysis flow (start)
The assumptions for this documents are:
* the Git repository has been created and contains little content
* a new API is required to be exposed
* no OpenAPI definition exists
* no API coding has commenced
* ApiCurio is the OpenAPI editor, and this has been linked to GitHub
It is beneficial if the objectives for the API and its high level
service domain scope have already been agreed before starting
to define the API.
Knowing the information to fetch or tasks that need to be performed
will assist in completing the API specification. This information
could be captured in the API specification so as to avoid duplicate
sources of information that needs to be synchronised.
Information in the OpenAPI specification can be extracted and rendered
into various formats, such as CSV lists of fields, their types,
size and description.
## Sequence Diagram
```mermaid
---
title: Business Analyst task flow
---
sequenceDiagram
actor ba as Business Analyst
participant ide as ApiCurio
participant git as Github
participant oas3f as OpenAPI file
Note over git, oas3f: The OpenAPI file is stored in Git
ba ->>+ ide: start IDE
ide ->> ide: Create new API
Note over ba, oas3f: New API is to meet naming standards for services
ide ->> ide: Create new data structures
Note over ba, oas3f: Data structures include requests and responses
ide ->> ide: Create new paths and methods
Note over ba, oas3f: Includes non 200 response handling, headers and security
ide ->>+ git: Commit to git
git ->>+ oas3f: OpenAPI file under Git
oas3f -->>- git: Saved
git --) git: Trigger GitActions for lint
git -->>- ide:
ide -->>- ba: close
```
When creating the OpenAPI specification the information to include:
* Summary and abstract
* Version
* Descriptions for fields
* Field attributes including mandatory, type, enumeration and rules such as size
* Descriptions for paths
A lint process will be run over the OpenAPI specification to ensure adherence
to styling standards.
# End Status of flow
At the end of this flow the OpenAPI (and/or AsyncAPI) specification will
be in a stable state so that coding can commence. Minor changes to the
specification can still occur, and completely new paths can be added.
When the specification changes the version will change according
to semantic versioning rules.
The OpenAPI definition generated is next used in the
[developer client start](developer_client_start.md) or
[developer server start](developer_server_start.md) flow.
The client will need to consume a mock service until the
server code is built.
# Reading Notes
Further automation can be achieved by GitActions calling
qaskx-cli, such as registering the OpenAPI specification in the
devops file.
The ApiCurio and Github components can be substituted for
other software products uch as Swagger Editor and Bitbucket
that provide similar capabilities.

29
docs/config/dot_qaskx.md 100644
View File

@ -0,0 +1,29 @@
# .qaskx file
The .qaskx (dotqaskx) file is normally located in
your home directory. The file is a basic, short
configuration file for items that are shared
across projects, such as your Git details.
A sample file is:
```json
{
"GitProvider": "git",
"GitHost": "https://tea.example.com",
"GitApi": "https://tea.example.com/api/v1",
"GitOrg": "Wardrobe",
"GitRepoUser": "meerkat",
"GitBranch": "main",
"GitUserEmail": "meerkat@example.com",
"Organisation": "Witch & Wardrobe",
"TemplateHost": "",
"TemplateFolder": "Xtreme/Folder/Template",
"Name": "Sir Meerkat",
"ServiceOwner": "Meerkat team, Sydney",
"ServiceOwnerEmail": "Meerkat.Team@example.com",
"PrimaryProgramLanguage": "go",
"LintApiLevel": ""
}
```

210
docs/developer_client_start.md 100644
View File

@ -0,0 +1,210 @@
# Front end client developer flow (start)
This is the initialisation of the front end
client code. Coding the server is covered in document
[developers server start](developers_server_start.md)
The [analysis start](analysis_start.md) is a pre-requisite for
this flow.
The assumptions for this documents are:
* the Git repository has been created
* a new API is required to be exposed
* an OpenAPI definition exists in Git
* no API coding has commenced
* Visual Studio Code has been installed
* Developer has access to the API editor viewer for the OpenAPI specification
## Sequence Diagram
### Automation
The sequence of automation activity using **devops** file and **qaskx-cli** is
as follows.
The Qaskx command line tool needs to be installed on the developer machine
```mermaid
---
title: Client development task flow
---
sequenceDiagram
actor dev as Developer
participant vsc as Visual Studio Code
participant term as Terminal
participant qaskx as qaskx-cli
participant cmdb as CMDB
participant git as Github
link git: GitHub @ https://github.com/meerkat-manor/devops
participant oas3f as OpenAPI file
participant devops as devops file
participant apip as API portal
dev ->>+ vsc: start IDE
Note over vsc, term: Clone existing git for project
vsc ->>+ git :
git -->>- vsc : Cloned, project opened
Note over git, devops: The OpenAPI and devops files are stored in Git
alt If no OpenAPI dependency linked
vsc -) devops: Update OpenAPI dependency entry
end
vsc ->>+ term: start
term ->>+ qaskx: New CMDB CI
qaskx ->>+ devops: Read
devops -->>- qaskx: Contents
loop Read called dependencies
qaskx ->>+ oas3f: Read dependency
oas3f -->>- qaskx: Contents
end
Note over cmdb, git: qaskx-cli rediops cmdb cmd
qaskx ->>+ cmdb:
cmdb -->>- qaskx: New CMDB CI value
qaskx -) devops: Update CMDB CI entry
qaskx -->>- term: Success
term ->>+ qaskx: Generate code
Note over qaskx, cmdb: qaskx-cli gen client cmd
qaskx ->>+ devops: Read dependency list
devops -->>- qaskx: Contents
loop Read called dependencies
qaskx ->>+ oas3f: Read dependency
oas3f -->>- qaskx: Contents
qaskx -) qaskx: Auto generate client code
end
qaskx -) qaskx: Auto generate sequence diagram
qaskx -) qaskx: Auto generate feature flags
qaskx -) devops: Auto update entries, including build, test
qaskx -->>- term: Success
alt Register using API dependencies if not already done
term ->>+ qaskx: Register API dependencies
Note over cmdb, git: qaskx-cli rediops register cmd
qaskx ->>+ devops: Read
devops -->>- qaskx: Contents
loop Read called dependencies
qaskx ->>+ oas3f: Read
oas3f -->>- qaskx: Contents
qaskx ->>+ apip:
apip -->>- qaskx: Registered as consumer
end
qaskx -) devops: Auto update API entry
qaskx -->>- term: Success
end
term -->- vsc: close
rect lightgrey
Note over vsc, qaskx: Developer codes to use the OpenAPI definition, with base code in place
vsc -->> vsc: Code update
vsc -->> vsc: Local build
vsc -->> vsc: Local test
end
vsc ->>+ git: Commit
git --) git: Trigger GitActions for lint, gateway, features, etc
git ->>- vsc: Success
vsc -->>- dev: close
```
### Manual
The equivalent sequence of manual activity, non qaskx actions is as follows.
The **devops** file is still used. Without **devops** file you will
follow whatever your existing process is and recorded the necessary
details in various documents
The OpenAPI tool needs to be installed on the developer machine.
```mermaid
---
title: Client development task flow
---
sequenceDiagram
actor dev as Developer
participant vsc as Visual Studio Code
participant cmdb as CMDB
link vsc: Visual Studio @ https://code.visualstudio.com/
participant term as Terminal
participant git as Github
link git: GitHub @ https://github.com/meerkat-manor/devops
participant oas3f as OpenAPI file
participant devops as devops file
participant oas3 as OpenAPI tool
participant apip as API portal
Note over cmdb, vsc: Create new CMDB CI entry for Client
dev ->>+ cmdb: Access UI
cmdb -->> cmdb: Create CMDB CI entry
cmdb -->>- dev: Close, noting CI value
Note over git, devops: The devops file is stored in Git
dev ->>+ vsc: start IDE
Note over cmdb, vsc: Clone existing git for project
vsc ->>+ git :
git -->>- vsc : Cloned, project opened
vsc -) devops: Update CMDB CI entry
vsc ->>+ term: start
Note over git, oas3: Set generation parameters
term ->>+ oas3: Generate code cmd
oas3 ->>+ oas3f: Read
oas3f -->>- oas3: Contents
oas3 -->>- term: Success
term -->- vsc: close
vsc -) vsc: Update client code with defaults
vsc -) vsc: Manually write sequence diagrams
vsc -) vsc: Manually write Gateway infra
vsc -) vsc: Manually write feature flags
alt Register using API dependencies if not already done
dev ->>+ apip: Register as consuming APIs
apip -->>- dev: Registered
end
vsc -) devops: Manually update entries
vsc ->>+ git: Commit
git --) git: Trigger GitActions for lint, gateway, features, etc
git ->>- vsc: Success
vsc -->>- dev: Done
```
# End Status of flow
At the end of this flow the basic code stubs exist and have been committed
to Github. The code can execute and will return not implemented
response results if the client is a non UI, headless consumer of the API.
For clients that will have a UI, the code will not work as no UI coding is
expected to have been done.
# Reading Notes
For automation, some activities can be performed by GitActions calling
qaskx-cli.
The Visual Studio Code, CMDB and Github components can be substituted for
other software products such IntelliJ and Bitbucket.

239
docs/developer_server_start.md 100644
View File

@ -0,0 +1,239 @@
# Back end server developer flow (start)
This is the initialisation of the back end
code. Coding the client is covered in document
[developers client start](developers_client_start.md)
The [analysis start](analysis_start.md) is a pre-requisite for
this flow.
The assumptions for this documents are:
* the Git repository has been created
* a new API is required to be exposed
* an OpenAPI definition exists in Git
* no API coding has commenced
* Visual Studio Code has been installed
* Developer has access to the API editor viewer for the OpenAPI specification
## Sequence Diagram
### Automation
The sequence of automation activity using **devops** file and **qaskx-cli** is
as follows.
**A server can also be a consumer of other APIs in which case it needs to generate
when downstream API specifications client code.**
The Qaskx command line tool needs to be installed on the developer machine
```mermaid
---
title: Server development task flow
---
sequenceDiagram
actor dev as Developer
participant vsc as Visual Studio Code
participant term as Terminal
participant qaskx as qaskx-cli
participant cmdb as CMDB
participant git as Github
link git: GitHub @ https://github.com/meerkat-manor/devops
participant oas3f as OpenAPI file
participant devops as devops file
participant apip as API portal
dev ->>+ vsc: start IDE
Note over vsc, term: Clone existing git for project
vsc ->>+ git :
git -->>- vsc : Cloned, project opened
Note over git, devops: The OpenAPI and devops files are stored in Git
vsc ->>+ term: start
term ->>+ qaskx: New CMDB CI
qaskx ->>+ devops: Read
devops -->>- qaskx: Contents
alt If no OpenAPI linked
qaskx ->>+ git:
Note over oas3f, devops: qaskx-cli rediops scan cmd
Note over oas3f, devops: Scan for OpenAPI file in Git
git -->>- qaskx:
qaskx -) devops: Update OpenAPI entry
end
qaskx ->>+ oas3f: Read
oas3f -->>- qaskx: Contents
Note over cmdb, git: qaskx-cli rediops cmdb cmd
qaskx ->>+ cmdb:
cmdb -->>- qaskx: New CMDB CI value
qaskx -) devops: Update CI entry
qaskx -->>- term: Success
term ->>+ qaskx: Generate code
Note over qaskx, cmdb: qaskx-cli gen server cmd
qaskx ->>+ devops: Read
devops -->>- qaskx: Contents
alt If no OpenAPI linked
qaskx ->>+ git:
Note over oas3f, devops: qaskx-cli rediops scan cmd
Note over oas3f, devops: Scan for OpenAPI file in Git
git -->>- qaskx:
qaskx -) devops: Update OpenAPI entry
end
qaskx ->>+ oas3f: Read
oas3f -->>- qaskx: Contents
qaskx -) qaskx: Auto generate server code
qaskx -) qaskx: Auto generate sequence diagram
qaskx -) qaskx: Auto generate gateway infra
qaskx -) qaskx: Auto generate feature flags
qaskx -) devops: Auto update entries, including build, test
qaskx -->>- term: Success
opt
term ->>+ qaskx: Generate code
Note over qaskx, cmdb: qaskx-cli gen client cmd
qaskx ->>+ devops: Read dependency list
devops -->>- qaskx: Contents
loop Read called dependencies
qaskx ->>+ oas3f: Read dependency
oas3f -->>- qaskx: Contents
qaskx -) qaskx: Auto generate client code
end
qaskx -->>- term: Success
end
rect lightgrey
Note over vsc, qaskx: Developer codes to use the OpenAPI definition, with base code in place
vsc -->> vsc: Code update
vsc -->> vsc: Local build
vsc -->> vsc: Local test
end
alt Register API if not already done
term ->>+ qaskx: Register API
Note over cmdb, git: qaskx-cli rediops register cmd
qaskx ->>+ devops: Read
devops -->>- qaskx: Contents
qaskx ->>+ oas3f: Read
oas3f -->>- qaskx: Contents
qaskx ->>+ apip:
apip -->>- qaskx: Registered
qaskx -) devops: Auto update API entry
qaskx -->>- term: Success
end
term -->- vsc: close
vsc ->>+ git: Commit
git --) git: Trigger GitActions for lint, gateway, features, etc
git ->>- vsc: Success
vsc -->>- dev: close
```
### Manual
The equivalent sequence of manual activity, non qaskx actions is as follows.
The **devops** file is still used. Without **devops** file you will
follow whatever your existing process is and recorded the necessary
details in various documents
The OpenAPI tool needs to be installed on the developer machine.
```mermaid
---
title: Server development task flow
---
sequenceDiagram
actor dev as Developer
participant vsc as Visual Studio Code
participant cmdb as CMDB
link vsc: Visual Studio @ https://code.visualstudio.com/
participant term as Terminal
participant git as Github
link git: GitHub @ https://github.com/meerkat-manor/devops
participant oas3f as OpenAPI file
participant devops as devops file
participant oas3 as OpenAPI tool
participant apip as API portal
Note over cmdb, vsc: Create new CMDB CI entry for API
dev ->>+ cmdb: Access UI
cmdb -->> cmdb: Create CI entry
cmdb -->>- dev: Close, noting CI value
Note over git, devops: The OpenAPI and devops files are stored in Git
dev ->>+ vsc: start IDE
Note over cmdb, vsc: Clone existing git for project
vsc ->>+ git :
git -->>- vsc : Cloned, project opened
vsc -) devops: Update CMDB CI entry
alt If no OpenAPI linked
vsc -) devops: Update OpenAPI entry
end
vsc ->>+ term: start
Note over git, oas3: Set generation parameters
term ->>+ oas3: Generate code cmd
oas3 ->>+ oas3f: Read
oas3f -->>- oas3: Contents
oas3 -->>- term: Success
term -->- vsc: close
vsc -) vsc: Update server code with defaults
vsc -) vsc: Manually write sequence diagrams
vsc -) vsc: Manually write Gateway infra
vsc -) vsc: Manually write feature flags
alt Register API if not already done
dev ->>+ apip: Register API
apip -->>- dev: Registered
end
vsc -) devops: Manually update entries
vsc ->>+ git: Commit
git --) git: Trigger GitActions for lint, gateway, features, etc
git ->>- vsc: Success
vsc -->>- dev: Done
```
# End Status of flow
At the end of this flow the basic code stubs exist and have been committed
to Github. The code can execute and will return not implemented
response results.
# Reading Notes
For automation, some activities can be performed by GitActions calling
qaskx-cli.
The Visual Studio Code, CMDB and Github components can be substituted for
other software products such IntelliJ and Bitbucket.

198
docs/developer_update.md 100644
View File

@ -0,0 +1,198 @@
# Developer update flow
_This document is intended to cover the scenario where the **devops**
file contents change including references to OpenAPI specifications._
## Update the OpenAPI specification
The OpenAPI specification as linked to the publishing server
is updated first.
```mermaid
---
title: Business Analyst update task flow
---
sequenceDiagram
actor ba as Business Analyst
participant ide as ApiCurio
participant git as Github
participant oas3f as OpenAPI file
Note over git, oas3f: The OpenAPI file is stored in Git
ba ->>+ ide: start IDE
ide ->> ide: Update API specification
ide ->> ide: Create / alter data structures
Note over ba, oas3f: Data structures include requests and responses
ide ->> ide: Create / alter new paths and methods
Note over ba, oas3f: Includes non 200 response handling, headers and security
ide ->> ide: Update the specification version
ide ->>+ git: Commit to git
git ->>+ oas3f: OpenAPI file under Git
oas3f -->>- git: Saved
git --) git: Trigger GitActions for lint
git -->>- ide:
ide -->>- ba: close
```
## Server update
Once the OpenAPI definition has been updated the server code needs to be
re-generated as the publisher of the API.
**A server can also be a consumer of other APIs in which case it needs updating
when downstream API specifications change.**
```mermaid
---
title: Server development update task flow
---
sequenceDiagram
actor dev as Developer
participant vsc as Visual Studio Code
participant term as Terminal
participant qaskx as qaskx-cli
participant git as Github
link git: GitHub @ https://github.com/meerkat-manor/devops
participant oas3f as OpenAPI file
participant devops as devops file
participant apip as API portal
dev ->>+ vsc: start IDE
Note over vsc, term: Clone existing git for project
vsc ->>+ git :
git -->>- vsc : Cloned, project opened
Note over git, devops: The OpenAPI and devops files are stored in Git
vsc ->>+ term: start
term ->>+ qaskx: Generate code
Note over qaskx, cmdb: qaskx-cli gen server cmd
qaskx ->>+ devops: Read
devops -->>- qaskx: Contents
qaskx ->>+ oas3f: Read
oas3f -->>- qaskx: Contents
qaskx -) qaskx: Auto generate server code
opt
qaskx -) qaskx: Auto generate sequence diagram
end
qaskx -->>- term: Success
opt
term ->>+ qaskx: Generate code
Note over qaskx, cmdb: qaskx-cli gen client cmd
qaskx ->>+ devops: Read dependency list
devops -->>- qaskx: Contents
loop Read called dependencies
qaskx ->>+ oas3f: Read dependency
oas3f -->>- qaskx: Contents
qaskx -) qaskx: Auto generate client code
end
qaskx -->>- term: Success
end
term -->- vsc: close
rect lightgrey
Note over vsc, qaskx: Code updates to use the updated OpenAPI definition
vsc -->> vsc: Code update
vsc -->> vsc: Local build
vsc -->> vsc: Local test
end
vsc ->>+ git: Commit
git --) git: Trigger GitActions for lint, gateway, features, etc
git ->>- vsc: Success
vsc -->>- dev: close
```
## Client update
Once the OpenAPI definition has been updated the client code needs to be
re-generated as the consumer of the API.
```mermaid
---
title: Client development update task flow
---
sequenceDiagram
actor dev as Developer
participant vsc as Visual Studio Code
participant term as Terminal
participant qaskx as qaskx-cli
participant git as Github
link git: GitHub @ https://github.com/meerkat-manor/devops
participant oas3f as OpenAPI file
participant devops as devops file
dev ->>+ vsc: start IDE
Note over vsc, term: Clone existing git for project
vsc ->>+ git :
git -->>- vsc : Cloned, project opened
vsc ->>+ term: start
term ->>+ qaskx: Generate code
Note over qaskx, cmdb: qaskx-cli gen client cmd
qaskx ->>+ devops: Read dependency list
devops -->>- qaskx: Contents
loop Read called dependencies
qaskx ->>+ oas3f: Read dependency
oas3f -->>- qaskx: Contents
qaskx -) qaskx: Auto generate client code
end
opt
qaskx -) qaskx: Auto generate sequence diagram
end
qaskx -->>- term: Success
term -->- vsc: close
rect lightgrey
Note over vsc, qaskx: Code updates to use the updated OpenAPI definition
vsc -->> vsc: Code update
vsc -->> vsc: Local build
vsc -->> vsc: Local test
end
vsc ->>+ git: Commit
git --) git: Trigger GitActions for lint, gateway, features, etc
git ->>- vsc: Success
vsc -->>- dev: close
```
The code is now updated with the latest OpenAPI definition
# End Status of flow
At the end of this flow the code has been updated with latest
definitions.
# Reading Notes
Using code generators will break the code in many situations and
therefore using Git and diff tools will help in identifying
what has changed and perform impact analysis.
In many situations with specification changes the compiler
will pick up the changes. Some changes can only be detected
at run time if there is a high level of abstraction.

93
docs/project_start.md 100644
View File

@ -0,0 +1,93 @@
# Project flow (start)
The project inception is when the scope of the project is
defined, but design and coding does not start immediately.
**Pause and reflect before starting to design and pause again
to reflect on the design before starting to code.**
With experience you will find that many times your initial gut instinct
on design is correct, but **many is not the same as always**. With the right
tools, refactoring does allow you to change designs/code quickly - but a
pause over lunch or a night's sleep costs little and can help
you organise your approach.
The sequence diagram below starts when you have an idea that you need
new code and existing code cannot be modified to suit your needs.
## Sequence diagram
```mermaid
sequenceDiagram
actor person as Team Member
participant term as Terminal
participant qaskx as qaskx-cli
participant git as Github
person ->>+ term: start
Note over term, git: Allocate repo name for server
term ->>+ qaskx:
Note over git: qaskx-cli rediops git (*) cmd
qaskx ->>+ git:
git -->>- qaskx: New git created
qaskx -->>- term: Success
term ->>+ git: git clone
git -->>- term:
term ->>+ qaskx: qaskx-cli rediops configure cmd
qaskx -->>- term:
term ->>+ git: git commit & push
git -->>- term:
opt Only applicable for new clients (web, mobile)
Note over term, git: Allocate repo name for client
term ->>+ qaskx:
Note over git: qaskx-cli rediops git (*) cmd
qaskx ->>+ git:
git -->>- qaskx: New git created
qaskx -->>- term: Success
term ->>+ git: git clone
git -->>- term:
term ->>+ qaskx: qaskx-cli rediops configure cmd
qaskx -->>- term:
term ->>+ git: git commit & push
git -->>- term:
end
term -->>- person:
```
The git repositories are now primed and ready for API specification.
The tasks in the sequence diagram is provisioning the required repositories.
The client repo may already exist for other functionality in which cas it is not
created, but will be used in the [developer client start](developer_client_start.md)
# End Status of flow
At the end of this flow the scope of the API delivery and the service domain
will be understood.
The project information is next used in the
[analysis start](analysis_start.md) flow.
# Reading Notes
A well defined service domain that is understood and agreed by all parties
will reduce rework effort, though with automation tools the manual effort
can be better managed.
A service domain can only return information or action requests that are
within its ability to fetch or remit to complete.

22
docs/readme.md 100644
View File

@ -0,0 +1,22 @@
# Contents
This is the location for documentation associated with
suggested the **rediops** process. The objective is to increase
the velocity of feature development by using tools to reduce
the repetitious tasks or at least reduce the number of keystrokes.
The documents should be read in the following sequence:
* [setup](setup.md) Once off desktop setup
* [project start](project_start.md) Starting a new project or initiative
* [analysis start](analysis_start.md) Focus on technical API analysis
* [developer server_start](developer_server_start.md) Initial server coding
* [developer client_start](developer_client_start.md) Initial client coding
* [developer update](developer_update.md) API updates during the development lifecycle
The process above is in the context of exposing functionality defined in
API service that can be consumed by clients - commonly a web or app user
interface.
**All flows are high level process depictions and can
be adjusted to suit your tools**

94
docs/setup.md 100644
View File

@ -0,0 +1,94 @@
# Setup desktop (start)
This is the setup desktop tasks that is performed by
the developers, though others that are updating code
including documentation can also perform the setup.
This task is expected to be done only once for a desktop
environment, and the environment can be used for
multiple projects and deliveries.
## Software installation
Please ensure the following tools or equivalents are
installed or you have access to servers with the
associated capabilities.
* A Git repository server - Github, Gitea
* Rights to create a Git repo and push content to the remote Git repo
* Git installed on local desktop
* Integrated development environment (IDE) software on local desktop - Visual Studio Code, IntelliJ
* Access to an OpenAPI editor - ApiCurio, Swagger UI
* Installed **qaskx-cli** tool on local desktop - download from *TBA*
* Access to a Configuration Management Database (CMDB) - ServiceNow, Zenoss
* Access to an API registry portal - Apiman.io, Redocly
The server based software above could be executed as docker images
on your local desktop, but this would be only for
demonstration purposes.
Configuring and initialising the software above is left for you to follow
any existing standards you may have. The qaskc-cli setup is below.
## Sequence diagram
The qaskx-cli has a setup command that creates the basic configuration
files that it uses. If or when you need to change the defaults, you will
commonly make the changes permanent by changing the configuration files.
This includes items such as:
* Your details and your organisation
* Your git details
* Preferred programming language
* Template (remote) locations
You can read further information on each file in documents:
* [.qaskx](config/dotaskx.md)
Now have a look at the steps below to setup the files.
```mermaid
sequenceDiagram
actor person as Team Member
participant term as Terminal
participant qaskx as qaskx-cli
participant home as home dir
participant prj as projects dir
person ->>+ term: start
Note over term, qaskx: Setup qaskx-cli tool
term ->>+ qaskx:
Note over qaskx, home: qaskx-cli setup configure cmd
qaskx ->>+ home:
home -->>- qaskx: New .qaskx file created
qaskx ->>+ prj:
prj -->>- qaskx: New config file created
qaskx -->>- term: Success
Note over term, home: You can rerun the configure or modify config file
term -->>- person:
```
# End Status of flow
At the end of the above setup steps the desktop will have the base tools
that are mentioned in subsequent documents, and you will have
access to the server features.
The next step in the process is covered in [project_start](project_start.md)
# Reading Notes
The suggested tools are only that, suggestions. You can substitute
your own preferred tools as appropriate. The concept is still valid
and your mileage may vary.

17
templates/default/.qaskx 100644
View File

@ -0,0 +1,17 @@
{
"GitProvider": "git",
"GitHost": "https://tea.example.com",
"GitApi": "https://tea.merebox.com/api/v1",
"GitOrg": "Wardrobe",
"GitRepoUser": "meerkat",
"GitBranch": "main",
"GitUserEmail": "meerkat@example.com",
"Organisation": "Witch & Wardrobe",
"TemplateHost": "",
"TemplateFolder": "Xtreme/Folder/Template",
"Name": "Sir Meerkat",
"ServiceOwner": "Meerkat team, Sydney",
"ServiceOwnerEmail": "Meerkat.Team@example.com",
"PrimaryProgramLanguage": "go",
"LintApiLevel": ""
}

134
templates/default/devops.json 100644
View File

@ -0,0 +1,134 @@
{
"apis": [
{
"api": {
"category": "API",
"name": "",
"url": ""
},
"format": "OpenAPI",
"guide": "",
"release_id": "",
"service_id": "",
"name": "AService",
"url": ""
},
{
"api": {
"category": "API",
"name": "",
"url": ""
},
"format": "AsyncAPI",
"guide": "",
"release_id": "",
"service_id": "",
"name": "BService",
"url": ""
}
],
"asset": {
"id": "b6775b43-659d-4426-b012-3226a7cfdd56",
"name": "",
"url": ""
},
"build": [
{
"activity": {
"category": "BUILD",
"name": "Lint",
"url": ""
},
"config": "",
"guide": ""
},
{
"activity": {
"category": "BUILD",
"name": "Compile",
"url": ""
},
"config": "",
"guide": ""
}
],
"created_on": "2023-07-09T07:05:38.8634596+10:00",
"dependency": {
"apis": [
{
"api": {
"category": "API",
"name": "",
"url": ""
},
"format": "OpenAPI",
"guide": "",
"release_id": "v1",
"service_id": "Customer.Details.CI00001",
"url": ""
}
],
"guide": "",
"tools": [
{
"commands": null,
"guide": "",
"playbook": "",
"tool": {
"category": "CUSTOM",
"name": "",
"url": ""
}
}
]
},
"devops_version": "0.0.1",
"guide": "",
"install": {
"commands": {
"script": ""
},
"deploy": {
"category": "DEPLOY",
"name": "rpm",
"url": ""
},
"guide": "",
"playbook": ""
},
"name": "Wardrobe",
"organisation": "Witch & Wardrobe",
"owner": {
"email": "",
"matrix": "",
"name": "",
"slack": "",
"twitter": "",
"web": ""
},
"tags": [
""
],
"test": [
{
"activity": {
"category": "TEST",
"name": "",
"url": ""
},
"config": "",
"guide": ""
},
{
"activity": {
"category": "TEST",
"name": "LoadRunner",
"url": ""
},
"config": "",
"guide": ""
}
],
"unique_id": "48913292-dc8a-4fb6-99cd-c22ab445e0ee",
"updated_on": "2023-07-09T07:05:38.8634596+10:00"
}