Skip to content

Use plain language #138

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Open
wants to merge 4 commits into
base: main
Choose a base branch
from
Open

Use plain language #138

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
4 commits
Select commit Hold shift + click to select a range
52b784d
Simplify language
abitrolly Sep 14, 2024
8236bb7
Explain what a devfile is in a cleaner way
abitrolly Sep 14, 2024
636be9f
Update libs/docs/src/docs/no-version/what-is-a-devfile.md
abitrolly Aug 2, 2025
7d51c1f
Update libs/docs/src/docs/no-version/what-is-a-devfile.md
abitrolly Aug 2, 2025
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
2 changes: 1 addition & 1 deletion apps/landing-page/pages/_app.tsx
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -82,7 +82,7 @@ function collectHeadings(
}

const websiteName = 'Devfile.io';
const websiteDescription = 'An open standard defining containerized development environments.';
const websiteDescription = 'An open standard for containerized development environments.';
const lfTrademarkUsageUrl = 'https://lfprojects.org/policies/';

function LandingPage({ Component, pageProps }: AppProps): JSX.Element {
Expand Down
2 changes: 1 addition & 1 deletion libs/core/src/components/hero/hero.tsx
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -72,7 +72,7 @@ export function Hero(): JSX.Element {
Simplify and accelerate your workflow.
</p>
<p className="mt-3 text-2xl tracking-tight text-slate-400">
An open standard defining containerized development environments.
An open standard for containerized development environments.
</p>
<div className="mt-8 flex gap-4 md:justify-center lg:justify-start">
<Button
Expand Down
18 changes: 8 additions & 10 deletions libs/docs/src/docs/no-version/what-is-a-devfile.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -3,16 +3,14 @@ title: What is a devfile
description: What is a devfile
---

You can use devfiles to automate and simplify your development process
by adopting the existing devfiles that are available in the [public community registry](https://registry.devfile.io/viewer)
or by authoring your own devfiles to record custom instructions to
configure and run your build environment as a YAML-formatted text file.
You can make these devfiles available in the supporting build tools and
IDEs that can automatically process the devfile instructions to configure
and build a running application from a development project.

Using the recommended best practices from the devfile, the tools and IDE
can:
`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).
Comment on lines +6 to +8
Copy link
Member

@michael-valdron michael-valdron Jul 31, 2025 •
edited
Loading

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Suggested change
`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).

Copy link
Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

The line is too long to see the diff.

Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

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.

Copy link
Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

@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.

Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

@abitrolly

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:

Suggested change
`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).

Copy link
Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

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.


Certain build tools and IDEs can automatically process the devfile
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Suggested change
Certain build tools and IDEs can automatically process the devfile
Certain developer tools and IDEs can automatically process the devfile

Copy link
Author

@abitrolly abitrolly Jul 31, 2025 •
edited
Loading

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

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.

Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

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.

@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.

Copy link
Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

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.

Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

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.

@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.

Copy link
Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

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,

to configure, build, and run an application from a development project.

Using devfile, the tools or IDE can:

- Take in the repository hosting your application source code.

Expand Down