Skip to content
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.

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

Readme reorganize #669

Merged

Conversation

qu1queee
Copy link
Contributor

Changes

Fixes #655

Note: Opening this PR for feedback on the ongoing efforts to improve our README and to understand what other issues we might require to make this ready. The current state of this PR is:

  • [1] Updates the main title from Shipwright - a framework for building container images on Kubernetes into Shipwright
  • [2] Adds as a first block a Why? section.
  • [3] Adds as a second block a Try It! section. @zhangtbj you can take some ideas of this one and leverage your current PR.
  • [4] Adds as a third block a Please tell me more! section. This one still incomplete. We will require new documents to properly provide more information for users that already try it, and that are looking forward to understand what else they can do. For example, how to build with Kaniko, or other strategies.
  • [5] Adds as a fourth block a More information section. This one still incomplete. Here we want to add all existing information around dependencies, existing documentation links, etc. We assume that a user that is at this block, might be willing to contribute eventually, therefore the need of providing as much context as possible before jumping into contributions or similar.
  • [6] Add as a fifth block a Want to get involved? section. This one is only reusing the existing information we have already in this file.

Submitter Checklist

  • Includes tests if functionality changed/was added
  • Includes docs if changes are user-facing
  • Set a kind label on this PR
  • Release notes block has been filled in, or marked NONE

See the contributor guide
for details on coding conventions, github and prow interactions, and the code review process.

Release Notes

Ensure the README is easier to digest and that it highlights the main value for Shipwright users.

@qu1queee qu1queee added do-not-merge/work-in-progress Indicates that a PR should not merge because it is a work in progress. kind/documentation Categorizes issue or PR as related to documentation. labels Mar 16, 2021
@openshift-ci-robot openshift-ci-robot added the release-note Label for when a PR has specified a release note label Mar 16, 2021
README.md Outdated Show resolved Hide resolved
README.md Outdated Show resolved Hide resolved
@openshift-ci-robot openshift-ci-robot added the needs-rebase Indicates a PR cannot be merged because it has merge conflicts with HEAD. label Mar 21, 2021
@adambkaplan adambkaplan added this to the release-v0.4.0 milestone Mar 22, 2021
@openshift-ci-robot openshift-ci-robot removed the needs-rebase Indicates a PR cannot be merged because it has merge conflicts with HEAD. label Mar 22, 2021
Copy link
Contributor

@HeavyWombat HeavyWombat left a comment

Choose a reason for hiding this comment

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

Just some things where I think we should change it a bit.

README.md Outdated Show resolved Hide resolved
README.md Outdated Show resolved Hide resolved
README.md Outdated Show resolved Hide resolved
README.md Outdated Show resolved Hide resolved
README.md Outdated Show resolved Hide resolved
README.md Outdated Show resolved Hide resolved
@qu1queee qu1queee force-pushed the readme_reorganize branch 18 times, most recently from 827f445 to 77e1987 Compare March 23, 2021 19:03
Drives users on how to use Kaniko for building a container image.
Remove a Try It! section for buildstrategies docs, not longer needed.
We have now a single Try It! in the main README
Doc that explains how to interact with the buildpacks stratey in order
to build a container image.
Copy link
Contributor

@imjasonh imjasonh left a comment

Choose a reason for hiding this comment

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

This looks great! I have some style nits and suggestions, but overall nothing serious or structural.

Nice work! 🎉

docs/tutorials/building_with_kaniko.md Outdated Show resolved Hide resolved
docs/tutorials/building_with_kaniko.md Outdated Show resolved Hide resolved
docs/tutorials/building_with_paketo.md Outdated Show resolved Hide resolved
docs/tutorials/building_with_paketo.md Outdated Show resolved Hide resolved
docs/tutorials/tutorial.md Outdated Show resolved Hide resolved
docs/tutorials/building_with_kaniko.md Outdated Show resolved Hide resolved
docs/tutorials/building_with_paketo.md Outdated Show resolved Hide resolved
docs/tutorials/building_with_paketo.md Outdated Show resolved Hide resolved
apiVersion: shipwright.io/v1alpha1
kind: BuildRun
metadata:
name: ruby-tutorial-buildrun
Copy link
Contributor

Choose a reason for hiding this comment

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

Suggested change
name: ruby-tutorial-buildrun
generateName: ruby-tutorial-buildrun-

apiVersion: shipwright.io/v1alpha1
kind: BuildRun
metadata:
name: go-tutorial-buildrun
Copy link
Contributor

Choose a reason for hiding this comment

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

Suggested change
name: go-tutorial-buildrun
generateName: go-tutorial-buildrun-

Copy link
Contributor Author

Choose a reason for hiding this comment

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

This was on purpose, otherwise it complicates the usage of kubectl get buildrun go-tutorial-buildrun -o json | jq '.status.conditions[]' command.

Copy link
Contributor

@imjasonh imjasonh left a comment

Choose a reason for hiding this comment

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

Couple more

README.md Outdated Show resolved Hide resolved
README.md Outdated Show resolved Hide resolved
README.md Outdated Show resolved Hide resolved
README.md Outdated Show resolved Hide resolved
README.md Outdated Show resolved Hide resolved
| **`Strategy`** | Refers to a particular tool that will be used when building a container image, such as Kaniko, Buildah, ko, etc. |
| **`Build`** | Resource used to define a build configuration. |
| **`BuildRun`** | Resource used to start the image build mechanism. |
| **`BuildStrategy/ClusterBuildStrategy`** | Resource that holds a template that dictates how to build via a particular strategy. |
Copy link
Contributor

Choose a reason for hiding this comment

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

Suggested change
| **`BuildStrategy/ClusterBuildStrategy`** | Resource that holds a template that dictates how to build via a particular strategy. |
| **`BuildStrategy/ClusterBuildStrategy`** | Resource that holds a template that describes how to build via a particular strategy. |

docs/tutorials/tutorial.md Outdated Show resolved Hide resolved
Copy link
Member

@SaschaSchwarze0 SaschaSchwarze0 left a comment

Choose a reason for hiding this comment

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

Nice rework. Some suggestions / corrections.

README.md Outdated Show resolved Hide resolved
README.md Outdated Show resolved Hide resolved
docs/tutorials/tutorial.md Outdated Show resolved Hide resolved
docs/tutorials/tutorial.md Outdated Show resolved Hide resolved
qu1queee and others added 2 commits March 29, 2021 17:46
Co-authored-by: Jason Hall <[email protected]>
Co-authored-by: Matthias Diester <[email protected]>
Co-authored-by: Sascha Schwarze <[email protected]>
Copy link
Member

@SaschaSchwarze0 SaschaSchwarze0 left a comment

Choose a reason for hiding this comment

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

Looks good.

@SaschaSchwarze0
Copy link
Member

/approve

@openshift-ci-robot openshift-ci-robot added the approved Indicates a PR has been approved by an approver from all required OWNERS files. label Mar 30, 2021
Rename tutorial.md to README.md
When listing strategies, follow an order of prio, based on
Other minor enhance around versions.
@openshift-ci-robot
Copy link

[APPROVALNOTIFIER] This PR is APPROVED

This pull-request has been approved by: SaschaSchwarze0

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

The pull request process is described here

Needs approval from an approver in each of these files:

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

@zhangtbj
Copy link
Contributor

/lgtm

@openshift-ci-robot openshift-ci-robot added the lgtm Indicates that a PR is ready to be merged. label Mar 30, 2021
@openshift-merge-robot openshift-merge-robot merged commit 4521398 into shipwright-io:master Mar 30, 2021
@qu1queee qu1queee deleted the readme_reorganize branch March 30, 2021 12:26
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Labels
approved Indicates a PR has been approved by an approver from all required OWNERS files. kind/documentation Categorizes issue or PR as related to documentation. lgtm Indicates that a PR is ready to be merged. release-note Label for when a PR has specified a release note
Projects
None yet
Development

Successfully merging this pull request may close these issues.

Reorganize README for end users
8 participants