docs: Update contribution documentation (#7639)

This attempts to improve some inaccuracies in the contribution documentation, as well as
making it clearer that opening an issue is preferred before committing
time to a PR.

Signed-off-by: Charlie Egan <[email protected]>

Author: charlieegan3

.github/PULL_REQUEST_TEMPLATE.md

@@ -23,9 +23,9 @@ familiar with signing off, see our contributor guide below.
 
 For more information on contributing to OPA see:
 
-* [Contributing Guide](https://www.openpolicyagent.org/docs/latest/contributing/)
+* [Contributing Guide](https://www.openpolicyagent.org/docs/contributing/)
   for high-level contributing guidelines and development setup.
-  (See the [Developer Certificate of Origin](https://www.openpolicyagent.org/docs/latest/contrib-code/#developer-certificate-of-origin)
+  (See the [Developer Certificate of Origin](https://www.openpolicyagent.org/docs/contrib-code/#developer-certificate-of-origin)
   section for specifics on signing off a commit.)
 
 -->

docs/docs/contrib-code.md

@@ -2,20 +2,19 @@
 title: Contributing Code
 ---
 
-## Code Contributions
+We are thrilled that you're interested in contributing to OPA! This document
+outlines some of the important guidelines when getting started as a new
+contributor. For developer environment setup, please refer to the
+[Contributing Development](./contrib-development/) page.
 
-If you are contributing code, please consider the following:
+When contributing please consider the following pointers:
 
 - Most changes should be accompanied with tests.
 - All commits must be signed off (see next section).
-- Related commits must be squashed before they are merged.
+- Related commits must be squashed before they are merged (this can be done in
+  the PR UI on GitHub).
 - All tests must pass and there must be no warnings from the `make check` target.
 
-If you are new to Go, consider reading
-[Effective Go](https://golang.org/doc/effective_go.html) and
-[Go Code Review Comments](https://github.com/golang/go/wiki/CodeReviewComments)
-for guidance on writing idiomatic Go code.
-
 When you implement new features in OPA, consider whether the
 types/functions you are adding need to be exported. Prefer
 unexported types and functions as much as possible.

docs/docs/contrib-development.md

@@ -2,15 +2,22 @@
 title: Development
 ---
 
-OPA is written in the [Go](https://golang.org) programming language.
+This page details the process for getting up and running locally for OPA
+development. If you're a first time contributor, we recommend you read through
+the [Contributing to OPA](./contrib-code) page first.
 
-If you are not familiar with Go we recommend you read through the [How to Write Go Code](https://golang.org/doc/code.html) article to familiarize yourself with the standard Go development environment.
+OPA is written in the [Go](https://golang.org) programming language.
+If you are new to Go, consider reading
+[Effective Go](https://golang.org/doc/effective_go.html),
+[Go Code Review Comments](https://go.dev/wiki/CodeReviewComments) or
+[How to Write Go Code](https://go.dev/doc/code)
+for guidance on writing idiomatic Go code.
 
 Requirements:
 
 - Git
 - GitHub account (if you are contributing)
-- Go (version 1.15+ is supported though older versions are likely to work)
+- Go (please see the project's [go.mod](https://github.com/open-policy-agent/opa/blob/main/go.mod) file for the current version in use)
 - GNU Make
 - Python3, pip, yamllint (if linting YAML files manually)
 

docs/docs/contributing.md

@@ -1,8 +1,11 @@
 ---
-title: How to contribute
+title: Contributing to OPA
+sidebar_label: Introduction
 ---
 
 Thanks for your interest in contributing to the Open Policy Agent project!
+There are all sorts of ways to get involved, whether you are a user of OPA or
+interested in contributing.
 
 :::info
 Most of the discussions about OPA take place on Slack, if you haven't already,
@@ -16,37 +19,47 @@ channel in Slack, hang out in there and see if there are any questions you
 can help with.
 
 You might also want to keep an eye on the
-[OPA Discussion Board](https://github.com/orgs/open-policy-agent/discussions).
+[OPA Discussion Board](https://github.com/orgs/open-policy-agent/discussions) or
+on the [`#rego`](https://stackoverflow.com/questions/tagged/rego) tag on Stack
+Overflow.
 
 ## I'd like to contribute code
 
-If you have found a bug and would like to work on a fix, we still encourage you
-file a [GitHub Issue](https://github.com/open-policy-agent/opa/issues) first
-to talk about the problem and the solution you have in mind.
+If you have found a bug and would like to work on a fix, **we always encourage you
+file a [GitHub Issue](https://github.com/open-policy-agent/opa/issues)** to talk
+about the problem and the solution you have in mind. This allows you to get
+feedback from maintainers before committing time to something that might already
+have a solution or might not be the right approach.
 
-Similarly, if you have an idea for a new feature, we encourage you to file an
-issue to discuss the feature before you start working on it too.
+If you have an idea for a new feature, we also **request that you file an
+issue** to discuss it first. This again allows you to get feedback from
+the maintainer team and the community before you start working on it.
 
 If you want to chat to the maintainers before opening an issue or about anything
 else, head over to
 [#contributors](https://openpolicyagent.slack.com/archives/C02L1TLPN59) in
 Slack.
 
-If you want to contribute code check out the
-[development reference](./contrib-development/) for pointers on how to get
+If you are ready to start contributing code, please see our
+[Contributing Code](./contrib-code/) guide for pointers on how to get
 started. Please note we have some restrictions around the use of AI tooling
 which are documented here.
 
 ## I'd like to help improve the documentation
 
-Great! Please see our [documentation page](./contrib-docs) for more details.
+Great! Please see our [Contributing Documentation](./contrib-docs) guide for
+more details.
 
 ## I have an OPA project or talk I'd like to share
 
-Awesome! For OPA-based projects, we have our [Ecosystem page](../ecosystem/).
-This is a great place to showcase your project. See
-[the instructions](https://github.com/open-policy-agent/opa/tree/main/docs#opa-ecosystem)
-here to get it listed.
+Awesome! For OPA-based projects, we have our [Ecosystem page](/ecosystem/).
+This is a great place to showcase your project and how it uses OPA.
+
+You can create a markdown file in:
+[`docs/src/data/ecosystem/entries`](https://github.com/open-policy-agent/opa/tree/main/docs/src/data/ecosystem/entries)
+and add an icon in
+[`/docs/static/img/ecosystem-entry-logos`](https://github.com/open-policy-agent/opa/tree/main/docs/static/img/ecosystem-entry-logos)
+to have your project listed on the ecosystem page.
 
 If you have a talk or blog you'd like to share please feel free to post in:
 

docs/src/lib/sidebars.js

@@ -87,8 +87,8 @@ module.exports = {
       collapsed: true,
       items: [
         "contributing",
-        "contrib-docs",
         "contrib-code",
+        "contrib-docs",
         "contrib-development",
         "contrib-adding-builtin-functions",
       ],