Skip to content

Latest commit

 

History

History
182 lines (123 loc) · 7.59 KB

github.md

File metadata and controls

182 lines (123 loc) · 7.59 KB
Raw

GitHub workflow for KServe documentation

Learn how to use GitHub and contribute to the kserve/website repo.

Set up your local machine

To check out your fork of the kserve/website repository:

  1. Create your own fork of the kserve/website repo.

  2. Configure GitHub access through SSH.

  3. Clone your fork to your machine and set the upstream remote to the kserve/website repository:

    mkdir -p ${GOPATH}/src/kserve.io
cd ${GOPATH}/src/kserve.io
git clone git@github.com:${YOUR_GITHUB_USERNAME}/website.git
cd docs
git remote add upstream https://github.com/kserve/website.git
git remote set-url --push upstream no_push

You are now able to open PRs, start reviews, and contribute fixes the kserve/website repo. See the following sections to learn more.

Important: Remember to regularly syncing your fork.

Report documentation issues

KServe uses Github issues to track documentation issues and requests. If you see a problem with the documentation that you're not sure how to fix, submit an issue using the following steps:

  1. Check the KServe docs issues list before creating an issue to avoid making a duplicate.

  2. Use the correct template for your new issue. There are two templates available:

    • Bug report: If you're reporting an error in the existing documentation, use this template. This could be anything from broken samples to typos. When you create a bug report, include as many details as possible and include suggested fixes to the issue.

    • Feature request: For upcoming changes to the documentation or requests for more information on a particular subject.

Open PRs to fix documentation issues

The KServe documentation follows the standard GitHub collaboration flow for Pull Requests (PRs).

  1. Ensure that your fork is up-to-date.

  2. Create a branch in your fork.

  3. Locate or create the file that you want to fix:

    • If you are updating an existing page, locate that file and begin making changes.

      For example, from any page on kserve.io, you can click the pencil icon in the upper right corner to open that page in GitHub.

    • If you are adding new content, you must follow the "new docs" instructions.

  4. To edit a file, use the new branch that you created in your fork.

    • Navigate to that same file within your fork using the GitHub UI.

    • Open that file from in your local clone.

  5. Create the Pull Request in the kserve/website repo.

  6. Assign an owner to the PR to request a review.

Here's what generally happens after you send the PR for review:

  1. One of the assigned repo maintainers will triage the PR by assigning relative priority, adding appropriate labels, and performing an initial documentation review.

  2. If the PR involves significant technical changes, for example new features, or new and changed sample code, the PR is assigned to a Subject Matter Expert (SME), typically an engineer working on KServe, for technical review and approval.

  3. When both the technical writers and SMEs are satisfied with the quality of the writing and the technical accuracy of the content, the PR can be merged. A PR requires two labels before it can merge: lgtm and approved.

    • The SME is responsible for reviewing the technical accuracy and adding the lgtm label.

    • The KServe technical writers are who provide the approved label when the content meets quality, clarity, and organization standards (see Style Guide).

We appreciate contributions to the docs, so if you open a PR we will help you get it merged.

Assigning owners and reviewers

All PRs should be assigned to a single owner ("Assignee"). It's best to set the "Assignee" and include other stakeholders as "Reviewers" rather than leaving it unassigned or allowing Prow to auto assign reviewers.

Use the /assign command to set the owner. For example: /assign @owner_id

For code related changes, initially set the owner of your PR to the SME who should review for technical accuracy. If you don't know who the appropriate owner is, nor who your reviewers should be for your PR, you can assign the current working group lead of the related component.

If you want to notify and include other stakeholders in your PR review, use the /cc command. For example: /cc @stakeholder_id1 @stakeholder_id2

Reviewing PRs

See the KServe community guidelines about reviewing PRs

Using Prow to manage PRs and Issues

KServe uses several sets of tools to manage pull requests (PR)s and issues in a more fine-grained way than GitHub permissions allow. In particular, you'll regularly interact with Prow to categorize and manage issues and PRs. Prow allows control of specific GitHub functionality without granting full "write" access to the repo (which would allow rewriting history and other dangerous operations). You'll most often use the following commands, but Prow will also chime in on most bugs and PRs with a link to all the known commands:

  • /assign @user1 @user2 to assign an issue or PR to specific people for review or approval.

  • /lgtm and /approve to approve a PR. Note that anyone may /lgtm a PR, but only someone listed in an OWNERS file may /approve the PR. A PR needs both an approval and an LGTM -- the /lgtm review is a good opportunity for non-approvers to practice and develop reviewing skills. /lgtm is removed when a PR is updated, but /approve is sticky -- once applied, anyone can supply an /lgtm.

  • Both Prow (legacy) and GitHub actions (preferred) can run tests on PRs; once all tests are passing and a PR has the lgtm and approved labels, Prow will submit the PR automatically.

  • You can also use Prow to manage labels on PRs with /kind ..., /good-first-issue, or /area ...

  • See Branches for details about how to use the /cherrypick command.

Common GitHub PRs FAQs

  • One or more tests are failing. If you do not see a specific error related to a change you made, and instead the errors are related to timeouts, try re-running the test at a later time. There are running tasks that could result in timeouts or rate limiting if your test runs at the same time.

  • Other Issues/Unsure -- reach out in the Slack channel and someone will be happy to help out.