Adds documentation on Devfile file reference #3487

cdrage · 2020-07-03T20:30:14Z

What type of PR is this?

/kind documentation
[skip ci]

TO PREVIEW: Click on: https://charliedrage.com/odo/file-reference/

What does does this PR do / why we need it:

This PR adds documentation regarding each section of Devfile and what we
support / do not support

Which issue(s) this PR fixes:

N/A

How to test changes / Special notes to the reviewer:

N/A

Signed-off-by: Charlie Drage charlie@charliedrage.com

openshift-ci-robot · 2020-07-03T20:30:47Z

[APPROVALNOTIFIER] This PR is NOT APPROVED

This pull-request has been approved by:
To complete the pull request process, please assign cdrage
You can assign the PR to them by writing /assign @cdrage in a comment when ready.

The full list of commands accepted by this bot can be found here.

Needs approval from an approver in each of these files:

docs/OWNERS

Approvers can indicate their approval by writing /approve in a comment
Approvers can cancel approval by writing /approve cancel in a comment

cdrage · 2020-07-03T20:31:30Z

Please NOTE:

The file formatting in this PR will be reflected within the gh-pages branch AFTER it's been merged.

I do need help with regards to figuring out which parts are implemented and not implemented yet, see: https://github.com/openshift/odo/pull/3487/files#diff-cbdbdd6ef8f9eed70da67b2888a01b64R116

cdrage · 2020-07-03T20:39:25Z

Document is best viewed in the markdown format: https://github.com/openshift/odo/blob/8da8401ae08f4a9b358dbe12c0855836b849323c/docs/file-reference/index.md

Specifically, the reason for the > note formatting + YAML + description is because I will be using https://github.com/slatedocs/slate for the output.

elsony · 2020-07-06T18:05:38Z

docs/file-reference/index.md

+
+# Introduction
+
+> A full odo Devfile example using Spring Boot


Should we move this example to somewhere below? I think it flows better if we describe what odo and devfiles are first before we start giving out devfile example.

Hi Elson, the example needs to remain as the first thing since this is consumed by https://github.com/slatedocs/slate

Could you elaborate, @cdrage, please? How is this document supposed to be consumed?

elsony · 2020-07-06T18:06:38Z

docs/file-reference/index.md

+
+**odo**
+
+odo is a fast, iterative, and straightforward CLI tool for developers who write, build, and deploy applications on OpenShift.


We support both Kubernetes and OpenShfit.

elsony · 2020-07-06T18:10:00Z

docs/file-reference/index.md

+
+What is a devfile?
+
+A devfile is a portable file that describes your development environment. It allows for a portable developmental environment without the need of reconfiguration.


Consider to change "It allows for a portable developmental environment.. " to "It allows reproducing a portable developmental environment... "

elsony · 2020-07-06T18:25:09Z

docs/file-reference/index.md

+
+With a devfile you can describe:
+
+* The source code being used


Consider to remove since I think it is the same as the last item (project).

elsony · 2020-07-06T18:29:53Z

docs/file-reference/index.md

+With a devfile you can describe:
+
+* The source code being used
+* Development components such as IDE tools (VSCode) and application runtimes (Yarn / NPM)


Given that for odo usage, our focus is on the container components (we don't even use IDE tools info in odo), consider to change to something like "Development components such as container definition for build and application runtimes."

elsony · 2020-07-06T19:00:29Z

docs/file-reference/index.md

+| name          | string                                      | yes      | Name of your endpoint                                                         |
+| targetPort    | integer                                     | yes      | Port number that you are targeting                                            |
+| configuration | [configurationObject](#configurationobject) | no       | Configuration attributes regarding the port number and protocol(s) being used |
+| attributes    | [attributesObject](#attributesobject)       | no       | UNKNOWN, TODO: FILL IN HERE!                                                  |


Attributes are optional map of free-form additional info.
Note: this applies to all attributes fields in all levels with a devfile, not specific to this one

elsony · 2020-07-06T19:04:00Z

docs/file-reference/index.md

+| github    | [githubObject](#githubobject) | Pull from GitHub                                                                   |
+| zip       | [zipObject](#zipobject)       | Get from a zip location                                                            |
+
+## gitObject


Consider to make all these object titles to be consistent, e.g. "git Object" instead of "gitObject".
Note: this comment applies to all object section titles

The reasoning for the camelCase is to fit with the other string, integer and boolean listings of variable types.

elsony · 2020-07-06T19:10:56Z

docs/file-reference/index.md

+
+| Key        | Type                      | Description               |
+|------------|---------------------------|---------------------------|
+| execObject | [execObject](#execobject) | The CLI command to be ran |


The key should be "exec"

Ah, you're right. Thanks

elsony · 2020-07-06T19:12:56Z

docs/file-reference/index.md

+| Key       | Type    | Required | Description                                                                    |
+|-----------|---------|----------|--------------------------------------------------------------------------------|
+| kind      | string  | yes      | Kind of group the command is part of. Options: `build`, `run`, `test`, `debug` |
+| isDefault | boolean | no       | Identifies that it is the default command to be ran                            |


Add: Only one default command can be defined for each group.

elsony · 2020-07-06T19:14:27Z

docs/file-reference/index.md

+| kind      | string  | yes      | Kind of group the command is part of. Options: `build`, `run`, `test`, `debug` |
+| isDefault | boolean | no       | Identifies that it is the default command to be ran                            |
+
+# Universal objects


attributes can be added to univerisal objects

johnmcollier · 2020-07-07T00:27:53Z

docs/file-reference/index.md

+> Download the application
+
+```sh
+$ odo create nodejs --downloadSource


Should be --starter now with #3425 merged

cdrage · 2020-07-07T18:31:28Z

Thanks for reviewing @elsony I've addressed your requested changes!

kadel · 2020-07-08T14:18:56Z

docs/file-reference/index.md

+If you haven't used odo yet, we recommend going through our [Deploying a devfile using odo guide](https://odo.dev/docs/deploying-a-devfile-using-odo/). 
+
+
+# Devfile Properties


Wouldn't be better to just link to official devfile reference? How are we going to keep this updated as devfile spec changes?

Agreed, as it stands, this is more a devfile doc which should probably live under the devfile project as it doesn't really have much information pertaining to what can be done with odo and devfiles…

@metacosm I do agree as well. I'm hoping we get this document upstream instead of the odo site, but unsure if we will be able to with time constraints regarding the alpha release of odo / Devfile v2.

cdrage · 2020-07-09T18:35:59Z

Hey all, to preview this please visit: https://charliedrage.com/odo/file-reference/

metacosm · 2020-07-10T15:07:31Z

docs/file-reference/index.md

+
+# Introduction
+
+> A full odo Devfile example using Spring Boot


Could you elaborate, @cdrage, please? How is this document supposed to be consumed?

metacosm · 2020-07-10T15:08:29Z

docs/file-reference/index.md

+        isDefault: true
+```
+
+> Download the application


That seems randomly put and completely unrelated to the perceived (at least by me) intent of the document…

metacosm · 2020-07-10T15:08:43Z

docs/file-reference/index.md

+$ odo push
+```
+
+**odo**


Why is this section needed?

metacosm · 2020-07-10T15:10:15Z

docs/file-reference/index.md

+
+What is a devfile?
+
+A devfile is a portable file that describes your development environment. It allows reproducing a portable developmental environment without the need of reconfiguration.


Portable how? What kind of development environment?

metacosm · 2020-07-10T15:11:04Z

docs/file-reference/index.md

+* A list of pre-defined commands that can be run
+* Projects to initially clone
+
+Odo takes this devfile and transforms it into a workspace of multiple containers running on OpenShift, Kubernetes or Docker.


What's a workspace?

metacosm · 2020-07-10T15:13:10Z

docs/file-reference/index.md

+
+Odo takes this devfile and transforms it into a workspace of multiple containers running on OpenShift, Kubernetes or Docker.
+
+Devfiles are YAML files with a defined schema.


It would still be helpful to repeat it here because that's where the information is needed.

metacosm · 2020-07-10T15:13:42Z

docs/file-reference/index.md

+
+Devfiles are YAML files with a defined schema.
+
+## Unsupported features


It would be better to start with supported features, in my opinion.

metacosm · 2020-07-10T15:16:59Z

docs/file-reference/index.md

+If you haven't used odo yet, we recommend going through our [Deploying a devfile using odo guide](https://odo.dev/docs/deploying-a-devfile-using-odo/). 
+
+
+# Devfile Properties


Agreed, as it stands, this is more a devfile doc which should probably live under the devfile project as it doesn't really have much information pertaining to what can be done with odo and devfiles…

openshift-ci-robot · 2020-07-13T18:00:22Z

@cdrage: The following test failed, say /retest to rerun all failed tests:

Test name	Commit	Details	Rerun command
ci/prow/v4.4-integration-e2e	`b383808`	link	`/test v4.4-integration-e2e`

Full PR test history. Your PR dashboard.

Instructions for interacting with me using PR comments are available here. If you have questions or suggestions related to my behavior, please file an issue against the kubernetes/test-infra repository. I understand the commands that are listed here.

metacosm · 2020-07-15T12:26:52Z

Why all the force pushes? Why are the tests run? It all makes it very difficult to follow up on the review… 😢

cdrage · 2020-07-15T13:51:46Z

Why all the force pushes? Why are the tests run? It all makes it very difficult to follow up on the review…

Force of habit haha! Should of put in separate commits.

Unfortunately tests are ran regardless even though it's only doc changes :(

Did you also have a look at the website preview with regards how to consume the file? https://charliedrage.com/odo/file-reference/

metacosm · 2020-07-16T10:10:08Z

Why all the force pushes? Why are the tests run? It all makes it very difficult to follow up on the review…

Force of habit haha! Should of put in separate commits.

Especially for docs, there really is no need to force push. This should only be reserved to cases where there is a conflict that needs to be fixed and, if possible, only after the review process is finished (though fixing the conflict might require a second pass).

Unfortunately tests are ran regardless even though it's only doc changes :(

You can specify that tests shouldn't run by adding [skip ci] to your commits (though I still think that CI should be skipped automatically for commits affecting some non-code paths)…

Did you also have a look at the website preview with regards how to consume the file? https://charliedrage.com/odo/file-reference/

Yes, thank you.

dharmit

Mostly naming suggestions.

docs/file-reference/index.md

**What type of PR is this?** > Uncomment only one ` /kind` line, and delete the rest. > For example, `> /kind bug` would simply become: `/kind bug` > Documentation changes: Please include [skip ci] in your commit message as well /kind documentation [skip ci] **What does does this PR do / why we need it**: This PR adds documentation regarding each section of Devfile and what we support / do not support **Which issue(s) this PR fixes**: N/A **How to test changes / Special notes to the reviewer**: N/A Signed-off-by: Charlie Drage <charlie@charliedrage.com>

cdrage · 2020-07-31T14:45:19Z

I will have to merge this as-is for now in order to get documentation in time for alpha release. We can update / edit this at a later date / go through this with the docs team @boczkowska @Preeticp

* Adds documentation on Devfile file reference (#3487) **What type of PR is this?** > Uncomment only one ` /kind` line, and delete the rest. > For example, `> /kind bug` would simply become: `/kind bug` > Documentation changes: Please include [skip ci] in your commit message as well /kind documentation [skip ci] **What does does this PR do / why we need it**: This PR adds documentation regarding each section of Devfile and what we support / do not support **Which issue(s) this PR fixes**: N/A **How to test changes / Special notes to the reviewer**: N/A Signed-off-by: Charlie Drage <charlie@charliedrage.com> * Update file reference documentation (#3675) **What type of PR is this?** > Uncomment only one ` /kind` line, and delete the rest. > For example, `> /kind bug` would simply become: `/kind bug` /kind documentation [skip ci] **What does does this PR do / why we need it**: Updates the file reference documentation to not have the introductory section and move unsupported features to the bottom. **Which issue(s) this PR fixes**: N/A **PR acceptance criteria**: N/A **How to test changes / Special notes to the reviewer**: N/A Signed-off-by: Charlie Drage <charlie@charliedrage.com> * make odo delete work on s2i components in experimental mode (#3649) * Fixes GetRunningPodNameByComponent for the CLI runners (#3666) * increase ResponseHeaderTimeout (#3674) * Make the file sync destination more consistent (#3662) * Make the file sync destination more consistent Signed-off-by: John Collier <John.J.Collier@ibm.com> * Update tests to use PROJECTS_ROOT Signed-off-by: John Collier <John.J.Collier@ibm.com> * Fix workdir in tests Signed-off-by: John Collier <John.J.Collier@ibm.com> * Remove more references to nodejs-starter Signed-off-by: John Collier <John.J.Collier@ibm.com> * Update more sample devfiles Signed-off-by: John Collier <John.J.Collier@ibm.com> * make odo catalog list components work outside of experimental mode (#3669) * make odo catalog list components work outside of experimental mode * moved the logic to cli * Ignore error while checking for imagestream support * rearranged the catalog list * Validate exec subcommands in a composite (#3658) * Validate exec subcommands in composite * Add integration test * added --s2i flag for `odo create` command * corrected error messages * Corrected flag description and validation * added --s2i flag for `odo create` command * Make Devfile the default deployment mechanism for odo **What type of PR is this?** > Uncomment only one ` /kind` line, and delete the rest. > For example, `> /kind bug` would simply become: `/kind bug` /kind feature **What does does this PR do / why we need it**: Makes Devfile the default deployment mechanism, removing S2I in favour of Devfile deployment. **Which issue(s) this PR fixes**: Closes #3550 **How to test changes / Special notes to the reviewer**: Run: ```sh odo preference set experimental false odo create --starter nodejs odo push ``` Co-authored-by: Girish Ramnani <girishramnani95@gmail.com> Co-authored-by: Mrinal Das <mrinald7@gmail.com> Co-authored-by: Tomas Kral <tkral@redhat.com> Co-authored-by: John Collier <John.J.Collier@ibm.com> Co-authored-by: Devang Gaur <devang.gaur.7@gmail.com>

openshift-ci-robot added the kind/documentation label Jul 3, 2020

openshift-ci-robot requested review from GeekArthur and girishramnani July 3, 2020 20:30

elsony suggested changes Jul 6, 2020

View reviewed changes

openshift-ci-robot assigned elsony Jul 6, 2020

johnmcollier reviewed Jul 7, 2020

View reviewed changes

cdrage force-pushed the file-reference branch from 8da8401 to 5f232ec Compare July 7, 2020 18:30

kadel reviewed Jul 8, 2020

View reviewed changes

metacosm suggested changes Jul 10, 2020

View reviewed changes

openshift-ci-robot assigned metacosm Jul 10, 2020

metacosm mentioned this pull request Jul 10, 2020

odo PR reviews snowdrop/team#113

Closed

cdrage force-pushed the file-reference branch 2 times, most recently from b1fd3bf to b383808 Compare July 13, 2020 14:50

dharmit suggested changes Jul 23, 2020

View reviewed changes

openshift-ci-robot assigned dharmit Jul 23, 2020

This was referenced Jul 23, 2020

Adds documentation on Devfile file reference snowdrop-zen/odo#10

Closed

Adds documentation on Devfile file reference snowdrop-zen/odo#11

Closed

cdrage force-pushed the file-reference branch from b383808 to f67bd7e Compare July 24, 2020 14:24

cdrage merged commit 9c93a29 into redhat-developer:master Jul 31, 2020

cdrage deleted the file-reference branch January 14, 2022 14:52


		# Introduction

		> A full odo Devfile example using Spring Boot


		odo

		odo is a fast, iterative, and straightforward CLI tool for developers who write, build, and deploy applications on OpenShift.


		What is a devfile?

		A devfile is a portable file that describes your development environment. It allows for a portable developmental environment without the need of reconfiguration.


		With a devfile you can describe:

		* The source code being used

		If you haven't used odo yet, we recommend going through our [Deploying a devfile using odo guide](https://odo.dev/docs/deploying-a-devfile-using-odo/).


		# Devfile Properties


		Odo takes this devfile and transforms it into a workspace of multiple containers running on OpenShift, Kubernetes or Docker.

		Devfiles are YAML files with a defined schema.


		Devfiles are YAML files with a defined schema.

		## Unsupported features

Adds documentation on Devfile file reference #3487

Adds documentation on Devfile file reference #3487

Conversation

cdrage commented Jul 3, 2020 • edited

openshift-ci-robot commented Jul 3, 2020

cdrage commented Jul 3, 2020

cdrage commented Jul 3, 2020

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

cdrage commented Jul 7, 2020

kadel Jul 8, 2020 • edited

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

cdrage commented Jul 9, 2020

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

openshift-ci-robot commented Jul 13, 2020 • edited

metacosm commented Jul 15, 2020

cdrage commented Jul 15, 2020

metacosm commented Jul 16, 2020 • edited

dharmit left a comment

Choose a reason for hiding this comment

cdrage commented Jul 31, 2020

cdrage commented Jul 3, 2020 •

edited

kadel Jul 8, 2020 •

edited

openshift-ci-robot commented Jul 13, 2020 •

edited

metacosm commented Jul 16, 2020 •

edited