Use plain language #138
Use plain language #138
Conversation
abitrolly
force-pushed
the
patch-1
branch
2 times, most recently
from
7d1e707 to
afdd3d4
Compare
There was a problem hiding this comment.
Hi @abitrolly,
After reviewing the PR list I noticed your PR to simplify and improve the current wording on our doc page describing a devfile, thank you for your contribution!
I've left some suggestion feedback on the rewording the devfile definition. Let me know what you think of these suggestions and apply any you'd like to accept.
Only other feedback I have aside from the suggestions is to rebase your branch. Request re-review from me once you're ready for me to take another look.
| `devfile.yaml` describes how to configure and run build environment for | ||
| your project in a development container. You can create devfile from scratch or | ||
| adopt existing from [public community registry](https://registry.devfile.io/viewer). |
There was a problem hiding this comment.
| `devfile.yaml` describes how to configure and run build environment for | |
| your project in a development container. You can create devfile from scratch or | |
| adopt existing from [public community registry](https://registry.devfile.io/viewer). | |
| The devfile, `devfile.yaml`, describes how to configure and run your workspace under a | |
| Kubernetes environment using a development container. You can create devfile workspace | |
| from scratch or adopt existing boilerplate devfile stack from the | |
| [public community registry](https://registry.devfile.io/viewer). |
There was a problem hiding this comment.
The line is too long to see the diff.
There was a problem hiding this comment.
The line is too long to see the diff.
@abitrolly Is this better? I doubt I can get it better, this block suggestion had a lot of changes suggested.
There was a problem hiding this comment.
@michael-valdron the formatting is better, but the definition of "workspace" is vague. The descriptions fits the example on how to run VSCode session in Kubernetes cluster, which is not the case. It is not what is the difference between "devfile" and "devfile workspace" here..
Also it looks like it is impossible to use devfile without Kubernetes. Not sure if that's the case.
There was a problem hiding this comment.
Also it looks like it is impossible to use devfile without Kubernetes. Not sure if that's the case.
You are correct, one other case is podman with odo, other cases though are Kubernetes currently.
but the definition of "workspace" is vague. The descriptions fits the example on how to run VSCode session in Kubernetes cluster, which is not the case. It is not what is the difference between "devfile" and "devfile workspace" here..
The devfile defines a project workspace that targets Kubernetes (or Podman), how commands are run for building, deploying, testing, etc. Depending on the devtool you could run your opened workspace in the cluster (Eclipse Che) or in an outside editor/IDE but connected (odo).
Perhaps this sounds better:
| `devfile.yaml` describes how to configure and run build environment for | |
| your project in a development container. You can create devfile from scratch or | |
| adopt existing from [public community registry](https://registry.devfile.io/viewer). | |
| The devfile, `devfile.yaml`, describes how to configure and run your workspace under a | |
| containerized environment using a development container. You can create a devfile from | |
| scratch or adopt existing boilerplate devfile stack from the | |
| [public community registry](https://registry.devfile.io/viewer). |
There was a problem hiding this comment.
The definition of "workspace" is still vague. For me "workspace" is setup for local or remote IDE with colors. fonts, plugins, open panes and stuff. The devfile doesn't describe this.
| your project in a development container. You can create devfile from scratch or | ||
| adopt existing from [public community registry](https://registry.devfile.io/viewer). | ||
|
|
||
| Certain build tools and IDEs can automatically process the devfile |
There was a problem hiding this comment.
| Certain build tools and IDEs can automatically process the devfile | |
| Certain developer tools and IDEs can automatically process the devfile |
There was a problem hiding this comment.
As I understand it, the devfile specifies how to build the project, so I guess the developer tool should be a tool that is able to build it. Plain podman won't be enough.
There was a problem hiding this comment.
As I understand it, the
devfilespecifies how to build the project, so I guess the developer tool should be a tool that is able to build it. Plainpodmanwon't be enough.
@abitrolly I corrected to developer tool because I consider consumer applications such as odo and Eclipse Che to be closer to that (Eclipse Che being an IDE), these do more than just building the project, with the devfile you can spec it to configure Che how to open up and use the workspace, you can also configure the devfile to define how Che or odo runs the commands you need for your workspace, even set init containers if needed.
Build tools are more like maven that focuses more on what to specific project needs to build such as setting the stack version and defining the dependencies of the project. You can use a devfile to use the build tools for the stack being used for the project, e.g. defining the maven commands to run in the developer container.
There was a problem hiding this comment.
I feel like the best here is to link "Certain tools" to a page describing what are the tools, what they do and what do they need the devfile for. Otherwise it is again too general to be useful.
There was a problem hiding this comment.
I feel like the best here is to link "Certain tools" to a page describing what are the tools, what they do and what do they need the
devfilefor. Otherwise it is again too general to be useful.
@abitrolly We have these tools listed under a documentation page, https://devfile.io/docs/2.3.0/developing-with-devfiles, are you asking that we link it here to provide more clarification on what is a devfile and its consumer tools?
We also need to be careful how specific we are being with this as devfile is an open standard for any tool that are used in this circumstance, so just stating that devfile is only for these list of tools does not communicate this the right way. I think if we stated it can be used with these list of tools would be sufficient enough.
There was a problem hiding this comment.
Tools that support devfile can automatically configure, build, and run an application from a development project. They can, for example:
Sounds better? Also removes the need in the next sentence,
|
[APPROVALNOTIFIER] This PR is NOT APPROVED This pull-request has been approved by: abitrolly The full list of commands accepted by this bot can be found here.
Needs approval from an approver in each of these files:
Approvers can indicate their approval by writing |
Signed-off-by: Anatoli Babenia <[email protected]>
Signed-off-by: Anatoli Babenia <[email protected]>
Co-authored-by: Michael Valdron <[email protected]>
Co-authored-by: Michael Valdron <[email protected]>
Description of Changes
Attempt to use less sophisticated language as explained in https://en.wikipedia.org/wiki/Plain_language
Acceptance Criteria
Update the sidebar if there is a new file added or an existing filename is changed
Tests Performed
Explain what tests you personally ran to ensure the changes are functioning as expected.
How To Test
Instructions for the reviewer on how to test your changes.
Notes To Reviewer
Any notes you would like to include for the reviewer.