[Docs] Cleanup docs on contributing

docs/source/conf.py

@@ -46,6 +46,16 @@
             """,
             "class": "",
         },
+        {
+            "name": "Discord",
+            "url": "https://discord.gg/KrZGbfZ7wm",
+            "html": """
+                <svg xmlns="http://www.w3.org/2000/svg" width="16" height="16" fill="currentColor" class="bi bi-discord" viewBox="0 0 16 16">
+                    <path d="M13.545 2.907a13.2 13.2 0 0 0-3.257-1.011.05.05 0 0 0-.052.025c-.141.25-.297.577-.406.833a12.2 12.2 0 0 0-3.658 0 8 8 0 0 0-.412-.833.05.05 0 0 0-.052-.025c-1.125.194-2.22.534-3.257 1.011a.04.04 0 0 0-.021.018C.356 6.024-.213 9.047.066 12.032q.003.022.021.037a13.3 13.3 0 0 0 3.995 2.02.05.05 0 0 0 .056-.019q.463-.63.818-1.329a.05.05 0 0 0-.01-.059l-.018-.011a9 9 0 0 1-1.248-.595.05.05 0 0 1-.02-.066l.015-.019q.127-.095.248-.195a.05.05 0 0 1 .051-.007c2.619 1.196 5.454 1.196 8.041 0a.05.05 0 0 1 .053.007q.121.1.248.195a.05.05 0 0 1-.004.085 8 8 0 0 1-1.249.594.05.05 0 0 0-.03.03.05.05 0 0 0 .003.041c.24.465.515.909.817 1.329a.05.05 0 0 0 .056.019 13.2 13.2 0 0 0 4.001-2.02.05.05 0 0 0 .021-.037c.334-3.451-.559-6.449-2.366-9.106a.03.03 0 0 0-.02-.019m-8.198 7.307c-.789 0-1.438-.724-1.438-1.612s.637-1.613 1.438-1.613c.807 0 1.45.73 1.438 1.613 0 .888-.637 1.612-1.438 1.612m5.316 0c-.788 0-1.438-.724-1.438-1.612s.637-1.613 1.438-1.613c.807 0 1.451.73 1.438 1.613 0 .888-.631 1.612-1.438 1.612"/>
+                </svg>            
+            """,
+            "class": "",
+        }
     ],
     "source_repository": "https://github.com/paraglider-project/paraglider/",
     "source_branch": "main",

docs/source/developers/contributing.rst

@@ -13,12 +13,11 @@ This page gives an overview of how to contribute to the project. Please read ove
 
    contributing/prerequisites.rst
    contributing/building.rst
-   contributing/contributing-issues.rst
    contributing/writing-go.rst
-   contributing/known-issues.rst
 
 Overview
 ----------
+
 Paraglider provides a streamlined interface for users to manage their cloud network resources.
 Cloud customers interact with the Paraglider APIs exposed by the Paraglider controller. 
 The controller is responsible for provisioning and updating the relevant cloud network resources based on the requests from the user. 
@@ -27,6 +26,7 @@ For more information about the design and architecture, please refer to :ref:`ho
 
 Guidelines
 ------------------
+
 We always welcome minor contributions like documentation improvements, typo corrections, bug fixes, and minor features in the form of pull requests. 
 You are also welcome to `choose an existing issue <https://github.com/paraglider-project/paraglider/issues>`_, or `create an issue to work on <https://github.com/paraglider-project/paraglider/issues/new>`_.
 
@@ -45,7 +45,7 @@ Contributors sign-off that they adhere to these requirements by adding a Signed-
 
     Signed-off-by: Random J Developer <[email protected]>
 
-We provide a Git Hook to automatically add this line to your commit messages. You can install it by running the following command after installing the repo.
+We provide a Git Hook to automatically add this line to your commit messages. You can install it by running the following command after cloning the repo.
 
 .. code-block:: console
 
@@ -57,13 +57,13 @@ If you'd like to do this manually, git has a ``-s`` command line option to appen
 
     $ git commit -s -m 'This is my commit message'
 
-Visual Studio Code has a setting, git.alwaysSignOff to automatically add a Signed-off-by line to commit messages. Search for "sign-off" in VS Code settings to find it and enable it.
-
+VS Code has a setting, git.alwaysSignOff to automatically add a Signed-off-by line to commit messages. Search for "sign-off" in VS Code settings to find it and enable it.
 
 Creating issues
 --------------------
-Please create issues for needed work and bugs in the `repo <https://github.com/paraglider-project/paraglider/issues>`_.
 
+Please create issues for needed work and bugs in the `repo <https://github.com/paraglider-project/paraglider/issues>`_.
+Please provide as much information as possible, including the version of the software you are using, the operating system, and the steps to reproduce the issue.
 
 Sending pull requests
 ----------------------
@@ -75,10 +75,7 @@ Code of Conduct
 This project has adopted the code of conduct defined by the Contributor Covenant to clarify expected behavior in our community.
 For more information, see the `Contributor Covenant Code of Conduct 2.1 <https://www.contributor-covenant.org/version/2/1/code_of_conduct/>`_.
 
-
 Troubleshooting and getting help
 ---------------------------------
-* Have a question? - Visit our Discord (linked on our homepage) to post your question and we'll get back to you ASAP
-* Found an issue? - Refer to :ref:`contributingissues` on filing a bug report
-* Have a proposal? - Refer to :ref:`contributingissues` for instructions on filing a feature request
 
+If you have a question, please visit our Discord (linked at the footer) to post your question and we'll get back to you ASAP

docs/source/developers/contributing/building.rst

@@ -5,9 +5,8 @@ Building The Project
 
 Building the code
 ------------------------
-Paraglider uses a Makefile to build the repository and automate most common repository tasks.
 
-You can run ``make`` (no additional arguments) to see the list of targets and their descriptions.
+Paraglider uses a Makefile to build the repository and automate most common repository tasks.
 
 You can build the repository with ``make build``. This will build all of the packages and executables. 
 The first time you run ``make build`` it may take a few minutes because it will download and build dependencies. Subsequent builds will be faster because they can use cached output.
@@ -18,13 +17,12 @@ The following command will build, run unit tests, and run linters. This command
 
     $ make build lint test
 
-Built binaries
+Binaries
 ^^^^^^^^^^^^^^^
+
 There are two main binaries that are built by the repository: ``glide`` and ``glided``. These are the CLIs for the Paraglider client and server, respectively.
 See the :ref:`api` for more information on how to use these binaries.
 
-Installing the code
-^^^^^^^^^^^^^^^^^^^^^
 After building the code, you can run ``make install`` to install the binaries to your ``/usr/local/bin`` directory. This will allow you to run the binaries from anywhere on your system.
 
 Documentation
@@ -57,13 +55,3 @@ Viewing
     $ python -m http.server
 
 Navigate to ``localhost:8000``.
-
-Troubleshooting and getting help
----------------------------------
-You might encounter error messages while running various ``make`` commands due to missing dependencies. Review the prerequisites listed above for installation instructions.
-
-If you get stuck working with the repository, please ask for help by `raising an issue on Github <https://github.com/paraglider-project/paraglider/issues/new>`_ or in our Discord (linked on our home page). 
-We're always interested in ways to improve the tooling, so please feel free to report problems and suggest improvements.
-
-If you need to report an issue with the Makefile, we may ask you for a dump of the variables. You can see the state of all of the variables our Makefile defines with ``make dump``. The output will be quite large so you might want to redirect this to a file.
-

docs/source/developers/contributing/prerequisites.rst

@@ -3,74 +3,61 @@
 Prerequisites
 =============
 
-Prerequisites for working with the repo
------------------------------------------
-This section lists the prerequisites for working with the repository. Most contributors should start with the basic prerequisites. 
+This section lists the prerequisites for working with the repository.
+Most contributors should start with the basic prerequisites. 
 Depending on the task you need to perform, you may need to install more tools.
 
-We also provide a `Devcontainer <https://code.visualstudio.com/docs/devcontainers/containers>`_ for working with this repository without installing prerequisites. 
-Keep reading for instructions.
+VS Code Setup
+-------------
 
-Operating system
-^^^^^^^^^^^^^^^^^^^^
-We support developing on macOS, Linux and Windows with `WSL <https://docs.microsoft.com/windows/wsl/install>`_.
-
-Asking for help
-^^^^^^^^^^^^^^^^^^^^
-If you get stuck installing any of our dependencies, you can raise an issue or ask for help in our `discord <https://discordapp.com/channels/1116864463832891502/11168644638328915074>`_.
-
-Required tools
-^^^^^^^^^^^^^^^^^^^^
-This is the list of core dependencies to install for the most common tasks. In general we expect all contributors to have all of these tools present:
+We recommend using VS Code for Paraglider development because we provide a `dev container <https://code.visualstudio.com/docs/devcontainers/containers>`_.
+Dev containers allow you to run a development environment using VS Code inside a container, which means you don't need to install any dependencies on your local machine.
 
-- `Git <https://git-scm.com>`_
-- `Go <https://golang.org/>`_
-- `golangci-lint <https://golangci-lint.run>`_
-- `protoc <https://grpc.io/docs/protoc-installation>`_
-- make
+#. `Get VS Code set up to use dev containers <https://code.visualstudio.com/docs/devcontainers/containers#_getting-started>`_.
+#. `In VS Code, open the cloned repository in a container <https://code.visualstudio.com/docs/devcontainers/containers#_quick-start-open-an-existing-folder-in-a-container>`_.
 
-  * Linux: Install the ``build-essential`` package:
-
-    .. code-block:: console
-
-        $ apt install build-essential
-
-    Then install ``make``:
+   .. note::
 
-    .. code-block:: console
+        The first time you open the repository in a container, it will take a while to download and install the prerequisites.
+        Subsequent opens will be much faster.
 
-        $ apt install make
-
-  * Mac:
+#. `Install the Go extension <https://marketplace.visualstudio.com/items?itemName=golang.go>`_.
+#. Configure linter.
+
+   You may see the following error from ``gopls`` in the ``*_test.go`` files.
 
-    Xcode
+      This file is within module ".", which is not included in your workspace.
+      To fix this problem, you can add a go.work file that uses this directory.
+      See the documentation for more information on setting up your workspace:
+      https://github.com/golang/tools/blob/master/gopls/doc/workspace.md.
 
-    .. code-block:: console  
-
-        $ xcode-select --install
-
-    Homebrew
+   Specify the following in your ``settings.json``.
 
-    .. code-block:: console
+   .. code-block:: json
 
-        $ brew install make
-
-Testing Required Tools
-^^^^^^^^^^^^^^^^^^^^^^^
-If you have not already done so, clone the repository and navigate there in your command shell.
+      "go.buildTags": "unit,integration,multicloud"
 
-You can build the main outputs using ``make``:
+Required Tools
+--------------
 
-.. code-block:: console
+This is the list of core dependencies to install for the most common tasks.
+In general we expect all contributors to have all of these tools present.
 
-    $ make build lint
+- `make <https://www.gnu.org/software/make/>`_
+- `Go <https://golang.org/>`_
+- `protoc <https://grpc.io/docs/protoc-installation>`_
+- `protoc-gen-go <https://pkg.go.dev/google.golang.org/protobuf/cmd/protoc-gen-go>`_
+- `protoc-gen-go-grpc <https://pkg.go.dev/google.golang.org/grpc/cmd/protoc-gen-go-grpc>`_
+- `redis <https://redis.io>`_
+- `golangci-lint <https://golangci-lint.run>`_
 
-Running these steps will run our build and lint steps and verify that the tools are installed correctly. 
-If you get stuck or suspect something is not working in these instructions please raise an issue or ask for help in our Discord linked on our homepage.
+Running Functional Tests
+------------------------
 
-**Integration/Multicloud Tests**
+Paraglider uses both unit and functional tests.
+While unit tests use a fake cloud provider, functional tests make API calls to real cloud providers, which requires further setup.
 
-Our integration/multicloud tests perform real requests to cloud providers. You can run these with the following commands
+You can run these with the following commands
 
 .. code-block:: console
 
@@ -79,9 +66,11 @@ Our integration/multicloud tests perform real requests to cloud providers. You c
 
 Note that the ``make test`` command only runs unit tests.
 
-If you would like to run these locally, you will need to be authenticated. The following are the steps for each respective cloud provider.
+If you would like to run these locally, you will need to be authenticated.
+The following are the steps for each respective cloud provider.
 
-**Google Cloud**
+Google Cloud
+^^^^^^^^^^^^
 
 #. `Install the gcloud CLI <https://cloud.google.com/sdk/docs/install>`_. If you're using the dev container, this will already be installed for you.
 #. `Set up your application default credentials <https://cloud.google.com/docs/authentication/provide-credentials-adc>`_.
@@ -94,13 +83,14 @@ If you would like to run these locally, you will need to be authenticated. The f
 
         This requires privileges of creating projects and linking billing accounts.
 
-   * If you want to use your own project, set the environment variable ``PARAGLIDER_GCP_PROJECT``. The order for deleting resources when deleting through the console: instances, VPN tunnels, VPN gateway + peer/external VPN gateways + router, VPC. The connectivity tests can be deleted at any time.
+   * If you want to use your own project instead of creating a new one, set the environment variable ``PARAGLIDER_GCP_PROJECT``. The order for deleting resources when deleting through the console: instances, VPN tunnels, VPN gateway + peer/external VPN gateways + router, VPC. The connectivity tests can be deleted at any time.
 
      .. warning::
 
-        Resources will not automatically be cleaned up for you.
+        The project will not be deleted, and resources allocated by the tests will not automatically be cleaned up for you.
 
-**Azure**
+Azure
+^^^^^
 
 #. `Install azure cli <https://learn.microsoft.com/en-us/cli/azure/install-azure-cli>`_. If you're using the dev container, this will already be installed for you.
 #. `Authenticate to your account with azure login <https://learn.microsoft.com/en-us/cli/azure/authenticate-azure-cli>`_.
@@ -112,50 +102,24 @@ If you would like to run these locally, you will need to be authenticated. The f
 
           Resource group must be created before running the test.
 
-
-If you'd like to persist resources after a test (i.e., not teardown project/resource group), you can set the environment variable ``PARAGLIDER_TEST_PERSIST`` to ``1``.
-
-**IBM** 
+IBM
+^^^
 
 #. Set environment variable ``PARAGLIDER_IBM_API_KEY`` with an ``IAM API`` key. Create a key on `IBM's web console <https://cloud.ibm.com/iam/apikeys>`_. 
 #. Set environment variable ``PARAGLIDER_IBM_RESOURCE_GROUP_ID`` with a resource group ID. 
    Pick a resource group from `IBM's web console <https://cloud.ibm.com/account/resource-groups>`__.
 
-| Cleanup function, terminating all Paraglider resources on IBM, is executed automatically when tests end, unless ``INVISINETS_TEST_PERSIST`` is set to ``1``.
-
-Editor
---------------------
-If you don't have a code editor set up for Go, we recommend VS Code. The experience with VS Code is high-quality and approachable for newcomers.
-
-Alternatively, you can choose whichever editor you are most comfortable for working on Go code. Feel free to skip this section if you want to make another choice.
-
-- `Visual Studio Code <https://code.visualstudio.com/>`_
-- `Go extension <https://marketplace.visualstudio.com/items?itemName=golang.go>`_
-
-Launching VS Code
+Persisting Resources
 ^^^^^^^^^^^^^^^^^^^^
-The best way to launch VS Code for Go is to do *File* > *Open Folder* on the repository. 
 
-You can easily do this from the command shell with ``code .``, which opens the current directory as a folder in VS Code.
-
-
-Using the Dev Container
-------------------------
-Dev Containers allow you to run a development environment using VS Code inside a container. If you want to try this:
-
-- Install `Docker <https://code.visualstudio.com/docs/devcontainers/containers#_system-requirements>`_
-- Install `VS Code <https://code.visualstudio.com/>`_
-- Install the `Dev Container extension <https://marketplace.visualstudio.com/items?itemName=ms-vscode-remote.remote-containers>`_
-
-Now when you open the Paraglider repo, you will be prompted with the option to open in a Dev Container. 
-This will take a few minutes the first time to download and build the container, but will be much faster on subsequent opens.
-
-Additional Tools
---------------------
+The functional tests will automatically clean up any resources they create before completing the test run.
+If you'd like to persist resources after a test (i.e., not teardown project/resource group), you can set the environment variable ``PARAGLIDER_TEST_PERSIST`` to ``1``.
 
-Test summaries
-^^^^^^^^^^^^^^^^^^^^
-The default ``go test`` output can be hard to read when you have many tests. We recommend ``gotestsum`` as a tool to solve this. 
-Our ``make test`` command will automatically use ``gotestsum`` if it is available.
+Optional Tools
+--------------
 
-- `gotestsum <https://github.com/gotestyourself/gotestsum#install>`_
+- `gotestsum <https://github.com/gotestyourself/gotestsum#install>`_ for better test summaries
+
+  The default ``go test`` output can be hard to read when you have many tests.
+  We recommend ``gotestsum`` as a tool to solve this. 
+  Our ``make test`` command will automatically use ``gotestsum`` if available.