databricks-cli/bundle/schema/README.md

### Overview

`docs/bundle_descriptions.json` contains both autogenerated as well as manually written
descriptions for the json schema. Specifically
1. `resources` : almost all descriptions are autogenerated from the OpenAPI spec
2. `environments` : almost all descriptions are copied over from root level entities (eg: `bundle`, `artifacts`)
3. `bundle` : manually editted
4. `include` : manually editted
5. `workspace` : manually editted
6. `artifacts` : manually editted

These descriptions are rendered in the inline documentation in an IDE

### SOP: Add schema descriptions for new fields in bundle config

1. You can autogenerate empty descriptions for the new fields by running
`bricks bundle schema --only-docs > ~/bricks/bundle/schema/docs/bundle_descriptions.json`
2. Manually edit bundle_descriptions.json to add your descriptions
3. Build again to embed the new `bundle_descriptions.json` into the binary (`go build`)
4. Again run `bricks bundle schema --only-docs > ~/bricks/bundle/schema/docs/bundle_descriptions.json` to copy over any applicable descriptions to `environments`
5. push to repo


### SOP: Update descriptions in resources from a newer openapi spec

1. Run `bricks bundle schema --only-docs --openapi PATH_TO_SPEC > ~/bricks/bundle/schema/docs/bundle_descriptions.json`
2. push to repo
Add openapi descriptions to bundle resources (#229) This PR: 1. Adds autogeneration of descriptions for `resources` field 2. Autogenerates empty descriptions for any properties in DABs 3. Defines SOPs for how to refresh these descriptions 4. Adds command to generate this documentation 5. Adds Automatically copy any descriptions over to `environments` property Basically it provides a framework for adding descriptions to the generated JSON schema Tested manually and using unit tests 2023-03-15 02:18:51 +00:00			`### Overview`

			`docs/bundle_descriptions.json` contains both autogenerated as well as manually written
			`descriptions for the json schema. Specifically`
			1. `resources` : almost all descriptions are autogenerated from the OpenAPI spec
			2. `environments` : almost all descriptions are copied over from root level entities (eg: `bundle`, `artifacts`)
			3. `bundle` : manually editted
			4. `include` : manually editted
			5. `workspace` : manually editted
			6. `artifacts` : manually editted

			`These descriptions are rendered in the inline documentation in an IDE`

			`### SOP: Add schema descriptions for new fields in bundle config`

			`1. You can autogenerate empty descriptions for the new fields by running`
			`bricks bundle schema --only-docs > ~/bricks/bundle/schema/docs/bundle_descriptions.json`
			`2. Manually edit bundle_descriptions.json to add your descriptions`
Add top level docs for bundle json schema (#313) Co-authored-by: Pieter Noordhuis <pieter.noordhuis@databricks.com> Co-authored-by: PaulCornellDB <paul.cornell@databricks.com> 2023-04-12 19:43:53 +00:00			3. Build again to embed the new `bundle_descriptions.json` into the binary (`go build`)
			4. Again run `bricks bundle schema --only-docs > ~/bricks/bundle/schema/docs/bundle_descriptions.json` to copy over any applicable descriptions to `environments`
			`5. push to repo`
Add openapi descriptions to bundle resources (#229) This PR: 1. Adds autogeneration of descriptions for `resources` field 2. Autogenerates empty descriptions for any properties in DABs 3. Defines SOPs for how to refresh these descriptions 4. Adds command to generate this documentation 5. Adds Automatically copy any descriptions over to `environments` property Basically it provides a framework for adding descriptions to the generated JSON schema Tested manually and using unit tests 2023-03-15 02:18:51 +00:00

			`### SOP: Update descriptions in resources from a newer openapi spec`

			1. Run `bricks bundle schema --only-docs --openapi PATH_TO_SPEC > ~/bricks/bundle/schema/docs/bundle_descriptions.json`
			`2. push to repo`