docs: improve landing pages for Contrib Guide (#3342)

Signed-off-by: Meg McRoberts <[email protected]>

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.

docs/docs/contribute/general/git/branch-create.md

@@ -13,29 +13,34 @@ 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 <my-new-branch>
 ```
 
+> **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:
 
 ```console
 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)

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:
 

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.

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.

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:
 

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.

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.

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.