redhat-appstudio / docs.appstudio.io

This repository is the official source of record for App Studio documentation.

Deprecated Document Notice

The documentation you are viewing is deprecated. For the latest updates on Konflux, review the Konflux documentation.

App Studio documentation

App Studio is an effort to automate build and delivery of Red Hat products. With App Studio, you have access to single, simple workflow for developing, testing, and releasing containerized applications while ensuring compliance with enterprise security standards.

App Studio documentation links

• Getting started guide
• User documentation
• Upstream landing page

External links

• HACDOCS project in JIRA
• HACBS hub on Confluence

Notes

This README file follows the content and syntax conventions defined in the Systems Design and Engineering Continuous Integration Git Repository README File Guide (The Source):

• https://source.redhat.com/groups/public/systems-design-and-engineering/continuousintegration/continuous_integration_wiki/xci_git_repository_readme_file

References for documentation team

• We used AsciiDoc to document App Studio (https://docs.asciidoctor.org/asciidoc/latest/#about-asciidoc).
• We created this website using Antora (https://docs.antora.org/antora/latest/). We use Antora because it provides a search capability that we can customize.

Required tools

A set of tools is required to render the documentation from Antora/AsciiDoc to HTML, and they need to be installed on the local machine:

• NodeJS, install the latest LTS version
• Golang, install the latest version
• Git, install the latest version

To install on Fedora Linux run the following command:

$ sudo dnf install nodejs golang git-core

Rendering the documentation

To render the documentation to HTML format run npm run build, this will output the rendered HTML files in the public subdirectory which can be opened in the browser.

For convenience there is also the dev script, that can be run with npm run dev to render and start a HTTP server at http://localhost:8080.

Jira workflow

1. Open Epics based on the doc plan.
2. Outline sprint/milestone.

• Follow up with SMEs to confirm their availability.

3. Break Epics down into tasks.

4. Discuss and assign tasks.

• New: on your queue but you haven’t started yet.

• Refinement: research it, read up on it, talk to SMEs about it. In a Jira comment, you can recap your research and SME conversations. You understand it enough to make a GDoc or Pull Request (PR).

• For bigger doc tasks, like creating entirely new documents, writing abstracts, developing procedures, etc., you might find it best to start in a GDoc.

• In the GDoc, you can receive reviews quickly and address reviews quickly. Once the doc is in good shape, you can take the content from the GDoc, and put in an ascii doc file and make a PR. This way, the PR is opened and closed quicker.

• In Progress: you’re now writing or making a file update. You have something to share beyond a Jira comment or status update.

• Review: you’ve elicited a peer review from docs, devs, and QE. You address the review as it comes. During the review stage, your content can be in either a GDoc or PR.

• Depending on the task, you might not need a review from all three: dev, doc, QE. For instance, fixing a broken link might only require a QE review. Changing a grammatical error might only require a doc review. Use your best judgment.

• Closed: reviews are complete and addressed. The PR is merged and the content is published.

Docs workflow with Dev and QE

1. Sprint planning.

• Does Docs have the bandwidth for this task?

• Will SMEs and QE be available to support Docs with this task for this sprint?

2. Research.

• Talke with SMEs. Gather information.

3. Review.

• If in a GDoc, add comments and update the GDoc until the content is ready to be converted into an ascii doc and shared in a PR.
• When the PR is created, the engineers review it and provide:
• Technical accuracy of content, not grammatical and language review.
• Provide user perspective.
• Writer responds to the review. Updates the Gdoc or PR and repeats until the review is complete and the doc is ready be published.

Git workflow

Forking and cloning GitHub repository

1. Fork the GitHub repository from the GitHub user interface (UI).
2. On the command line interface (CLI) on your local machine, run the following commands:
3. git clone [email protected]:<your-github-username>/<github repository you’re cloning>.git
4. cd <github repository>
5. git remote add -f upstream <[email protected]>/<github repository>
6. git checkout main
7. git remote -v

• Run this command to confirm that you have origin and upstream configured.

8. Now you’re ready to start contributing!

Making a pull request (PR)

1. cd <name of place where you stored the cloned repo/<name of repo> Ex: cd documents/docs.appstudio.io/
2. git checkout main
3. git fetch upstream Git data from upstream repo (the main repo)
4. git merge upstream/main Update what’s on my local repo (my cloned repo, on my machine)
5. git push

• To make sure your fork is now up to date with your local copy

• You could say “git push origin” but it’s superfluous because it’s always origin :)

• Now everything is up to date (main, fork, clone)

6. git checkout -b <feature-branch>

• Make the name of the feature branch the same name as the issue
• Ex: git checkout -b Stonesoup-170 upstream/main

7. Make doc changes.

• Make the doc changes in your chosen editor: Atom, VS Code, etc.

8. Run antora to check and test your doc changes on a local host server

• There’s multiple ways to build docs locally with Antora, we’ll need to determine a way

9. git status

• Verifies that the files you made changes to have been registered as a changed file, and therefore, can be committed.

10. git add .

• . is a terminal thing.

• . means THIS directory. So it means add files from this current directory you’re on

• git add you’re adding stuff to git stage.

• You could actually list the doc instead of the . the . is easy because it adds EVERYTHING that has been changed. So you can add like 3 files to one commit. If no ., then you have to manually add each file!

11. git status

• Double check that your file is in fact staged to be committed.

• Your file(s) will be highlighted green in the CLI once they’ve been added. If it’s not highlighted green, it was not added to be committed :)

12. git commit -m <name of commit message>

• Simply ready to be pushed.

• Ex: git commit -m Stonesoup-170 restructured procedure steps

13. git push -u origin <feature branch>

• This command creates the PR, and the PR is asking to merge your feature branch into the main repository.

• You don’t need git push -upstream origin <feature branch> remember, origin is the default. Like in step 5, it’s superfluous. You’re already on feature branch and staged the commit, so simply push it!

14. Go to GitHub to make the PR

15. Tag people, write messages, do what you must to receive peer reviews of your newly created PR.

Making commits for a PR

1. cd <location of repo>/<name of repo>

2. git checkout main

3. git fetch upstream

4. git merge upstream/main

5. git push

• To make clone and fork up-to-date with master

6. git checkout <feature-branch>

7. git pull --ff-only

• These command makes sure your feature branch (always on your fork) is nync with the master repo (upstream), hence why we merge to main

8. Make doc changes

9. Run antora to check and test your doc changes on a local host server

10. git status

11. git add .

12. git status

• Double check that your file is in fact staged to be committed.

• Your file(s) will be highlighted green in the CLI once they’ve been added. If it’s not highlighted green, it was not added to be committed :)

13. git commit --amend

• This will add any updates to your previous commit within the PR. If you do want to create a 2nd commit in the PR, run the command: git commit -m <name of commit message>

14. git push

• After you make a PR, you ought to be able to simply run git push to make a new commit. If you get any error messages, try git push -u origin <feature branch>

15. Go to PR to ensure the commit has been made.

• Tag reviewers, direct their attention to specific areas of content or whatever you see fit.

To generate output

• On your system: After setup (to set up follow reference information) run the following command on your terminal: npx antora --fetch antora-playbook.yml

• Merge you changes and refresh the App Studio documentation link, which is, https://redhat-appstudio.github.io/docs.appstudio.io/Documentation/main

docs.appstudio.io's Issues

Screenshots

In my current PR, Danny raised a good point about screenshots. I'm creating an issue here to remind us as a team to have a conversation about screenshots in the docs--whether we want them or not, and if we do, how we'll keep them updated.

Need procedure for adding EC as integration test

Title says most of what you need to know: We have a concept module for the EC, which is nice and all, but we don't actually tell users how to use the EC. They need to add it as an integration test, after customizing their pipeline (otherwise it'll absolutely fail), by following the instructions here (on page 14, under "Add integration test"): https://docs.google.com/document/d/1Vdmxey3sZvRDc6hcI4NjL89wHTh6DKXYTjA5zoa8Ok8/edit#

Getting started: No samples

At the time of this issue, the getting started page reads:

Getting started with Konflux
Signing up Go to Konflux

Click Join waitlist.

Creating your first application

We include ready-to-use bundled code samples that you can import into our service. In this
guide, we’ll walk you through how to fork a sample repository and create your first
application. To begin, click Create an application.

Choosing a bundled sample
Scroll to Select a sample and choose one of the following options:

Node.js
Quarkus
Spring Boot
Python
Go

However, in the WebUI there is no "Select a sample" list. After an application is created, none of the options/buttons/links appear like they would lead to a "Select a sample" choice.

No environments, no settings in current release

https://www.screencast.com/t/tgsOPJoQca8

Unclear when we will have end-user manual CRUD on environments

[Doc]: Update instruction of how to "add Integration Tests"

From doc: https://redhat-appstudio.github.io/docs.appstudio.io/Documentation/main/how-to-guides/testing_applications/proc_adding_an_integration_test/
I cannot connect these steps from what I see in my "Add integration test" tab.

What I am asked to fill in from UI :

• Integration test name
• Image bundle
• Pipeline to run

I think the documentation is asking to point to a GitHub repo which has a Tekton Pipeline yaml resides there, but the UI requires a bundle image and must have layer of Pipeline in it.

No tab title for CLI guide

When I view https://redhat-appstudio.github.io/docs.appstudio.io/Documentation/main/getting-started/getting_started_in_cli/ in my browser, the tab says "Untitled :: App Studio Documentation". It seems to be missing whatever metadata normally provides the article title there.

When I look at https://redhat-appstudio.github.io/docs.appstudio.io/Documentation/main/getting-started/get-started/ it shows a title.

Perhaps because the CLI guide starts with an h2 instead of an h1?

Remove label checks from "Surface-level tests"

The label checks are moving. They are no longer considered a test. Instead, these checks will be performed by the Enterprise Contract. Let's remove them from being mentioned in the docs for surface-level tests.

cc @dirgim, @arewm

How to Guide for Customizing your Pipeline

Docs Feature Request

Add a "how to" guide for users to customize their pipeline. Topics may include:

• Initiating and accepting the custom pipeline pull request.
• Modifying the input parameters for the pipeline and individual tasks.
• Extending the pipeline with your own tasks.

Cloning procedure feedback

Apologies I didn't get to a review of the PR yesterday, but taking a look at https://redhat-appstudio.github.io/docs.appstudio.io/Documentation/main/how-to-guides/managing-applications/proc-managing_applications/ I have a couple things I wanted to mention.

The Prerequisite section for "Cloning applications to a dedicated or all workspaces" doesn't mention they should already have the desired target workspace created and ready before running the export command.

The section header includes "or all workspaces", which it used to mention in a previous iteration, but we weren't sure if there was a use case for that, and looks like that procedure was removed. Should the header be updated to remove "or all", since it only covers exporting to a single destination workspace?

In the next section, the command example still includes the sample "build" as the app name. Could that be updated to match the first section, and use a variable format (like <name_of_your_application>)?

Diagram

We need a diagram that might include the following:
Git Source Repo ->
Stonesoup Build ->
Container Image Pushed to Quay.io ->
Auto Deployment to Stonesoup Development Environment ->
Stonesoup Enterprise Contract (optional) Test (SP) ->
Auto Deployment to Stonesoup Staging Environment (SP)

Applications page: All "learn more" links are broken

After creating a new application, under "What's next?" on the RHS are a set of buttons with "Learn More" links next to them. Clicking on each takes me to a 404 page.

placeholder.com links in getting-started/roles_persmissions/

When viewing https://redhat-appstudio.github.io/docs.appstudio.io/Documentation/main/getting-started/roles_persmissions/ there are a couple placeholder links that are clickable, but link to placeholder.com, which is a site, apparently, but not very relevant for us :)