From 77b2c6d333023ac1a84f4680df8796a3e1eac571 Mon Sep 17 00:00:00 2001 From: Meg McRoberts Date: Tue, 26 Mar 2024 05:17:08 -0700 Subject: [PATCH] docs: improve landing pages for Contrib Guide (#3342) Signed-off-by: Meg McRoberts --- .../general/contrib-guidelines-gen.md | 24 +++++-- .../contribute/general/git/branch-create.md | 15 +++-- .../docs/contribute/general/git/fork-clone.md | 2 +- docs/docs/contribute/general/git/index.md | 8 ++- docs/docs/contribute/general/git/pr-create.md | 66 +++++++++++-------- docs/docs/contribute/general/git/review.md | 2 +- docs/docs/contribute/general/index.md | 37 +++++++++-- docs/docs/contribute/index.md | 33 ++++++++-- docs/docs/contribute/software/index.md | 19 ++++-- 9 files changed, 149 insertions(+), 57 deletions(-) diff --git a/docs/docs/contribute/general/contrib-guidelines-gen.md b/docs/docs/contribute/general/contrib-guidelines-gen.md index 6e358536e1..a25ceba1bc 100644 --- a/docs/docs/contribute/general/contrib-guidelines-gen.md +++ b/docs/docs/contribute/general/contrib-guidelines-gen.md @@ -52,10 +52,22 @@ please create an issue on the GitHub repository. * When proposing new work, start by creating an issue or ticket in the project's [issue tracker](https://github.com/keptn/lifecycle-toolkit/issues). -* Actively participate in the refinement sessions that are part of the weekly + If you would like to work on this issue, include that in a comment to the issue. +* Actively participate in the + [refinement sessions](refinement-guide.md) + that are part of the regularly scheduled [community meetings](https://community.cncf.io/keptn-community/). -* In these sessions, everyone discusses the proposed work, whether it is a good idea, - what exactly should be done and how it aligns with the project goals. -* After the discussions, maintainers engage in a process known as **Scrum Poker**. - This involves a voting mechanism where maintainers collectively assess the size - and complexity of the proposed work, helping to decide whether it should proceed. + * In these sessions, everyone discusses the proposed work, whether it is a good idea, + what exactly should be done and how it aligns with the project goals. + * After the discussions, maintainers engage in a process known as **Scrum Poker**. + This involves a voting mechanism where maintainers collectively assess the size + and complexity of the proposed work, helping to decide whether it should proceed. + * When the issue is refined, it can be assigned and work can begin. +* A PR should be created within a week of when an issue is assigned to you + or the issue may be reassigned to someone else. + When necessary, you can request an extension from the maintainers + but the general expectation is that issues will be resolved + soon after they are assigned. +* In general, you must complete one issue before you are assigned another one. + Exceptions may be made when one issue is nearly completed + but we discourage contributors claiming multiple issues at one time. diff --git a/docs/docs/contribute/general/git/branch-create.md b/docs/docs/contribute/general/git/branch-create.md index 0d19a29ff3..4e272ca984 100644 --- a/docs/docs/contribute/general/git/branch-create.md +++ b/docs/docs/contribute/general/git/branch-create.md @@ -13,15 +13,20 @@ you need to create a local branch where you will make your changes. Be sure that your branch is based on and sync'ed with `main`, unless you intend to create a derivative PR. -The following sequence of commands does that: +The following sequence of commands does this: ```console git checkout main -git pull upstream main +git pull --rebase upstream main git push origin main git checkout -b ``` +> **Note** Be sure to do this each time you start a new PR. +> If you do not rebase to the `upstream main` branch, +> you may end up including the content from a previous PR in your new PR, +> which is not normally what you want. + Execute the following and check the output to ensure that your branch is set up correctly: @@ -29,13 +34,13 @@ to ensure that your branch is set up correctly: git status ``` -Now you can make your changes, build and test them locally, -then create a PR to add these changes to the documentation set. +Now you can make your changes and build and test them locally, +before you create a PR to add these changes to the documentation set. * For documentation changes: * Do the writing you want to do in your local branch * Check the formatted version in your IDE - or at `localhost:1314/docs-dev` + or at `localhost:8000/docs-dev` to ensure that it is rendering correctly and that all links are valid.. See [Build Documentation Locally](../../docs/local-building.md) diff --git a/docs/docs/contribute/general/git/fork-clone.md b/docs/docs/contribute/general/git/fork-clone.md index 942b1cb898..4141695019 100644 --- a/docs/docs/contribute/general/git/fork-clone.md +++ b/docs/docs/contribute/general/git/fork-clone.md @@ -15,7 +15,7 @@ of the Keptn repository on your local machine: * Choose the user for the fork from the options you are given, usually your GitHub ID. - A copy of this repository is now available in your GitHub account. + A copy of this repository is now available in your GitHub account. 2. Get the string to use when cloning your fork: diff --git a/docs/docs/contribute/general/git/index.md b/docs/docs/contribute/general/git/index.md index 325dba857d..6eb503a90f 100644 --- a/docs/docs/contribute/general/git/index.md +++ b/docs/docs/contribute/general/git/index.md @@ -13,10 +13,16 @@ and summarizes some standard practices we use with Keptn. You can also modify the source using the GitHub editor. This is very useful when you want to fix a typo or make some other small change -although be sure so include the DCO signoff. +although be sure to include the +[DCO](../dco.md) +signoff. If you are doing significant work, you should fork and clone your own copy of the repository, make your changes in a local branch, then push those changes to GitHub where they can be reviewed and ultimately merged into the product. +This is all done using standard Git commands; +the pages in this subsection describe a set of Git commands +that work well for the required steps +although you are free to use alternate Git steps if you prefer. diff --git a/docs/docs/contribute/general/git/pr-create.md b/docs/docs/contribute/general/git/pr-create.md index bf82cafd00..51b6f0a93b 100644 --- a/docs/docs/contribute/general/git/pr-create.md +++ b/docs/docs/contribute/general/git/pr-create.md @@ -18,7 +18,7 @@ This is a two-step process: The steps to push your new content from your local branch to the repository are: -1. When you have completed the writing you want to do, +1. When you have completed the writing you want to do and tested it, close all files in your branch and run `git status` to confirm that it correctly reflects the files you have modified, added, and deleted and does not include any files that you do not want to push. @@ -27,44 +27,47 @@ to the repository are: and ensure that it is up to date with the `main` Keptn branch: - ```bash - git remote add upstream https://github.com/keptn/lifecycle-toolkit.git - git checkout main - git pull upstream main - ``` + ```bash + git remote add upstream https://github.com/keptn/lifecycle-toolkit.git + git checkout main + git pull upstream main + ``` - Then update your feature branch from your local copy of `main` and push it: +1. Update your feature branch from your local copy of `main` and push it: - ```bash - git checkout feature/123/foo - git rebase main - git push --set-upstream origin feature/123/foo - ``` + ```bash + git checkout feature/123/foo + git rebase main + git push --set-upstream origin feature/123/foo + ``` 1. Add and commit your changes. The `git commit -s` command commits the files and signs that you are contributing this intellectual property to the Keptn project. - See the DCO docs for more information. + See [DCO](../dco.md) for more information. Here, we commit all modified files but you can specify individual files to the `git add` command. - ```console - git add . - git commit -s - ``` + ```console + git add . + git commit -s + ``` - Use vi commands to add a description of the PR - (should be 80 characters or less) to the commit. - The title text should be prefixed with an appropriate - [commit type](#commit-types) - to conform to our semantic commit scheme. - This title is displayed as the title of the PR in listings. + Use `vi` commands to add a description of the PR to the commit; + this description is displayed as the title of the PR in listings. - You can add multiple lines explaining the PR here but, in general, - it is better to only supply the PR title here; - you can add more information and edit the PR title - when you create the PR on the GitHub UI page. + * The title text should be prefixed with an appropriate + [commit type](#commit-types) + to conform to our semantic commit scheme. + * Follow the `commit type` with a brief (80 characters or less) description + that succinctly describes the change made by this PR. + The description must begin with a lowercase letter. + + You can add multiple lines explaining the PR here but, in general, + it is better to only supply the PR title here; + you can add more information and edit the PR title + when you create the PR on the GitHub UI page. 1. Push your branch to github. If you cloned your fork to use SSH, the command is: @@ -122,6 +125,15 @@ feat(api): new endpoint for feature X * Anything else that will help reviewers understand the scope and purpose of this PR. +* The PR template includes a checklist that must be filled out + to ensure that the PR adheres to the project requirements. + + * The template includes separate sections for software and documentation; + delete the section that does not apply to your PR, + unless your PR includes both software and documentation. + * Read each item and only check it off if you have satisfied that requirement. + * If a requirement is not relevant for your PR, mark it as `n/a` (not applicable). + * If you have **breaking changes** in your PR, it is important to note them in both the PR description and in the merge commit for that PR. diff --git a/docs/docs/contribute/general/git/review.md b/docs/docs/contribute/general/git/review.md index a53d7e64fd..408454a4d7 100644 --- a/docs/docs/contribute/general/git/review.md +++ b/docs/docs/contribute/general/git/review.md @@ -62,7 +62,7 @@ to ensure that all tests are still passing. When your PR has the appropriate approvals, it will be merged and the revised content should be published on the -website (as part of the `development` release) +website (as part of the `latest` release) within a few minutes. You can now delete your local branch with the following command: diff --git a/docs/docs/contribute/general/index.md b/docs/docs/contribute/general/index.md index 359d010c21..ba8c997ddc 100644 --- a/docs/docs/contribute/general/index.md +++ b/docs/docs/contribute/general/index.md @@ -4,10 +4,35 @@ comments: true # General information about contributing -This section is under development. -Contents are not complete, -but all material here has been reviewed for technical accuracy. +This section includes information that applies +to all types of contributions -- +software, documentation, and tests: -Keptn software and documentation -is developed and maintained by the Keptn community. -We invite you to join us. +- [Technologies and concepts you should know](technologies.md) + gives links to resources you can use to increase your knowledge if necessary. + +- [Codespaces](codespace.md) tells how to use GitHub Codespaces + to contribute to Keptn. + This is useful for Windows users who may find it difficult + to install a local development environment + and for Linux and MacOS users who may want to easily make a small contribution + without having to set up a full local environment. + +- [Working with Git](git/index.md) summarizes the steps required + to fork and clone a local copy of the repository, + create a local branch where you create your new content, + then submit that content as a PR + then shepherd that PR through the review process until it is merged. + +- [Contribution guidelines](contrib-guidelines-gen.md) summarizes + practices to help you succeed as a contributor. + These guidelines apply to all contributions; + a list of additional guidelines that apply only to documentation contributions + is given in + [Contribution guidelines for documentation](../docs/contrib-guidelines-docs.md). + +- [Refinement Process](refinement-guide.md) + explains how proposed issues are evaluated and approved for action. + +- [Release Checklist](release-checklist.md) + is a list of tasks that must be created when releasing a new Keptn version. diff --git a/docs/docs/contribute/index.md b/docs/docs/contribute/index.md index 8d996505a7..28f51d60c5 100644 --- a/docs/docs/contribute/index.md +++ b/docs/docs/contribute/index.md @@ -4,10 +4,35 @@ comments: true # Contributing to Keptn -This section is under development. -Contents are not complete, -but all material here has been reviewed for technical accuracy. - Keptn software and documentation is developed and maintained by the Keptn community. We invite you to join us. +This guide provides instructions and guidelines +for contributing software, documentation, and tests to Keptn. + +Keptn software, documentation, and tests are stored in the same +[Keptn](https://github.com/keptn/lifecycle-toolkit) +GitHub repository. +We use similar processes for all contributions. + +This guide provides useful information about how to contribute to the Keptn project. +It is divided into three sections: + +* [General](general/index.md) includes information + that is relevant to all contributions, including + information you should know about the technologies used, + instructions for creating a PR that contains your contribution + by either forking and cloning the repo and creating contributions locally + or working in Github Codespaces, + and guidelines that apply to all contributions. + +* [Software contributions](software/index.md) + includes information about how to set up an environment + for developing and testing Keptn software + as well as specific instructions for creating a new + Keptn metrics provider. + +* [Documentation contributions](docs/index.md) + gives additional guidelines that apply only to documentation contributions + and describes the documentation file structure + and the documentation tools we use. diff --git a/docs/docs/contribute/software/index.md b/docs/docs/contribute/software/index.md index 8a8c592bed..541b28bc0a 100644 --- a/docs/docs/contribute/software/index.md +++ b/docs/docs/contribute/software/index.md @@ -4,10 +4,17 @@ comments: true # Software contributions -This section is under development. -Contents are not complete, -but all material here has been reviewed for technical accuracy. +This section provides information specific to Keptn software development. +It supplements the information in the +[General](../general/index.md) section +that applies to all Keptn development. -Keptn software and documentation -is developed and maintained by the Keptn community. -We invite you to join us. +This section includes: + +- [Software development environment](dev-environ.md) + describes the steps required to set up a software development environment + where you can develop and test software contributions. + It includes a video walkthrough that illustrates the process. + +- [Add a metrics provider](add-new-metric-provider.md) + explains how to add support for a new metrics provider to Keptn.