Remaining /prob/ docs

docs/prob/api/internal-server-error.md

@@ -16,7 +16,7 @@ gone terribly wrong that the API does not recognise then this error is reported.
 
 ## Possible causes
 
-If a Go panic occurrs in one of the endpoints, then the API will quickly
+If a Go panic occurs in one of the endpoints, then the API will quickly
 recover, return a `/prob/api/internal-server-error` response to the client,
 and then most probably shutdown.
 

docs/prob/api/invalid-param.md

@@ -0,0 +1,54 @@
+# Problem: Invalid API parameter
+
+<!-- panels:start -->
+
+<!-- div:right-panel -->
+
+- Title: `Invalid API parameter.`
+- Type: `/prob/api/invalid-param`
+
+<!-- div:left-panel -->
+
+Parsing or validating a value sent to the API failed.
+
+<!-- panels:end -->
+
+## Possible causes
+
+<!-- panels:start -->
+
+<!-- div:left-panel -->
+
+Most fields are validated in the frontend, but if you're calling the backend API
+directly or if there is some validation rule missing in the frontend, then this
+problem may arise.
+
+The problem is related to the backend trying to parse or validate an input value
+but fails because of an invalid value.
+
+This problem is the fallback error for any special parameter types. Meaning,
+that this problem does not describe in detail which field was invalid or in what
+way it was considered invalid.
+
+<!-- div:right-panel -->
+
+Non-exhaustive list of potential issues:
+
+- invalid date format,
+- text string that is too long or too short (too many or too few characters),
+- URL that's missing the protocol (`https://`),
+- submitting "F" when only "A", "B", or "C" is allowed,
+- *or potentially something divergent from the above.*
+
+<!-- panels:end -->
+
+## Resolving it
+
+The problem detail message that is provided by the error message should be able
+to lead you to understanding the issue at hands.
+
+If you cannot resolve it yourself using the error message, try to contact your
+administrator / operations team that manages your Wharf instance.
+
+If that fails, try promoting the issue over to the Wharf developers over at
+GitHub as an issue: <https://github.com/iver-wharf/wharf-api/issues/new>

docs/prob/api/missing-param-string.md

@@ -0,0 +1,47 @@
+# Problem: Missing string value
+
+<!-- panels:start -->
+
+<!-- div:right-panel -->
+
+- Title: `Missing string value.`
+- Type: `/prob/api/missing-param-string`
+
+<!-- div:left-panel -->
+
+A text string was omitted or left empty in a web request.
+
+<!-- panels:end -->
+
+## Possible causes
+
+<!-- panels:start -->
+
+<!-- div:left-panel -->
+
+Most fields are validated in the frontend, but if you're calling the backend API
+directly or if there is some validation rule missing in the frontend, then this
+problem may arise.
+
+The problem is related to the backend expecting a string (text) value but
+received none, or that the received string was empty (zero length).
+
+<!-- div:right-panel -->
+
+For example, if you started a new build, but the name of the stage to run did
+not get sent (due to bug in the web page), then the API server could respond
+with:
+
+> **Missing string value.** \
+> A string value (text) was expected on parameter "stage", but it was either
+> omitted or empty.
+
+<!-- panels:end -->
+
+## Resolving it
+
+If you cannot resolve it yourself using the error message, try to contact your
+administrator / operations team that manages your Wharf instance.
+
+If that fails, try promoting the issue over to the Wharf developers over at
+GitHub as an issue: <https://github.com/iver-wharf/wharf-api/issues/new>

docs/prob/api/project/cannot-change-group.md

@@ -0,0 +1,40 @@
+# Problem: Project group cannot be changed
+
+<!-- panels:start -->
+
+<!-- div:right-panel -->
+
+- Title: `Project group cannot be changed.`
+- Type: `/prob/api/project/cannot-change-group`
+
+<!-- div:left-panel -->
+
+Once a project has been imported into Wharf, it is not allowed to have its group
+changed.
+
+<!-- panels:end -->
+
+## Possible causes
+
+This occurs when you update the group field on a project.
+
+There are some things that are locked in projects and cannot be changed. The
+project ID and project group name, to name a few.
+
+The project group field cannot be updated manually through Wharf's web interface
+on its own, but if you were to move a project from one user to another, or from
+one GitHub organization to another, followed by refreshing the project, then
+this problem could appear.
+
+## Resolving it
+
+Try importing the project from scratch, instead of trying to refresh the already
+imported project.
+
+If you receive the same error when importing from scratch, then you would need
+to delete the project from Wharf's database. As of the time of writing
+(2021-05-18), that would be done by sending an HTTP
+`DELETE /api/project/{projectid}` request to Wharf's API.
+
+If that fails, try promoting the issue over to the Wharf developers over at
+GitHub as an issue: <https://github.com/iver-wharf/wharf-api/issues/new>

docs/prob/api/project/run/params-deserialize.md

@@ -0,0 +1,59 @@
+# Problem: Parsing build parameters failed
+
+<!-- panels:start -->
+
+<!-- div:right-panel -->
+
+- Title: `Parsing build parameters failed.`
+- Type: `/prob/api/project/run/params-deserialize`
+
+<!-- div:left-panel -->
+
+Failed to parse build input parameters when starting a new build.
+
+<!-- panels:end -->
+
+## Possible causes
+
+<!-- panels:start -->
+
+<!-- div:left-panel -->
+
+Most fields are validated in the frontend, but if you're calling the backend API
+directly or if there is some validation rule missing in the frontend, then this
+problem may arise.
+
+Each build allows optional input parameters/[input variables](/usage-wharfyml/variables/input-variables.md)
+if they are defined in the projects [`.wharf-ci.yml`](/usage-wharfyml/) file.
+When starting a new build, you are allowed to set custom values for these
+variables on a per-build basis.
+
+If Wharf's API fails to parse these values that you've sent it, or fails to
+parse the input variable definitions of the project's build definition
+(`.wharf-ci.yml` file) itself, then this problem may arise.
+Such as if the value types of the input variables you've sent along or if the
+HTTP request payload is malformed.
+
+<!-- div:right-panel -->
+
+Examples:
+
+- The value `"foo bar"` is sent as the value for a `number`-typed input variable. 
+
+- HTTP request body to `POST /api/project/{projectid}/{stage}/run` is invalid
+  JSON or empty.
+
+<!-- panels:end -->
+
+## Resolving it
+
+In the case that you've entered a type of invalid format (ex: text string where
+a number of solely digits was expected) in Wharf's web interface then you can
+correct your mistake and try again. It would behoove us if you also reported the
+issue to the frontend GitHub repository as an issue: <https://github.com/iver-wharf/wharf-web/issues/new>
+
+If you cannot resolve it yourself using the error message, try to contact your
+administrator / operations team that manages your Wharf instance.
+
+If that fails, try promoting the issue over to the Wharf developers over at
+GitHub as an issue: <https://github.com/iver-wharf/wharf-api/issues/new>

docs/prob/api/project/run/params-serialize.md

@@ -0,0 +1,38 @@
+# Problem: Serializing build parameters failed
+
+<!-- panels:start -->
+
+<!-- div:right-panel -->
+
+- Title: `Serializing build parameters failed.`
+- Type: `/prob/api/project/run/params-serialize`
+
+<!-- div:left-panel -->
+
+Failed to compose build parameters to be forwarded to the execution engine when
+starting a new build.
+
+<!-- panels:end -->
+
+## Possible causes
+
+It's uncommon for Wharf's API to fail at this stage, but it comes from when it
+prepares the values it needs to send to the execution engine. This involves more
+than just the optional input parameters/[input variables](/usage-wharfyml/variables/input-variables.md)
+that you submit when starting a new build, but also a lot of other data such as
+the build ID, project name, Git clone URL, et.al.
+
+This usually means there has been a bug or regression in the Wharf API's
+codebase which lead it to produce this error.
+
+If Wharf's API fails to parse the values that you've sent it, then you are
+instead presented with the [`/prob/api/project/run/params-deserialize`](/prob/api/project/run/params-deserialize)
+problem.
+
+## Resolving it
+
+If you cannot resolve it yourself using the error message, try to contact your
+administrator / operations team that manages your Wharf instance.
+
+If that fails, try promoting the issue over to the Wharf developers over at
+GitHub as an issue: <https://github.com/iver-wharf/wharf-api/issues/new>

docs/prob/api/project/run/trigger.md

@@ -0,0 +1,57 @@
+# Problem: Triggering build failed
+
+<!-- panels:start -->
+
+<!-- div:right-panel -->
+
+- Title: `Triggering build failed.`
+- Type: `/prob/api/project/run/trigger`
+
+<!-- div:left-panel -->
+
+Wharf's API failed to communicate with the execution engine and tell it to start
+executing the build.
+
+<!-- panels:end -->
+
+## Possible causes
+
+<!-- panels:start -->
+
+<!-- div:left-panel -->
+
+There are plentyful of reasons why the Wharf API has been unable to talk with
+the execution engine. Most of these issues are operations-related, meaning that
+it's something with how your Wharf installation has been set up.
+
+Potential causes ranges from network issues, to TLS/certificate issues, or even
+as mundane issues such as someone accidentally shut it off.
+
+<!-- div:right-panel -->
+
+Examples:
+
+- Execution engine was offline when the Wharf API tried to communicate with it
+  (ex: restarting, failed to start, or being relocated to a different server by
+  [Kubernetes' evicion policies](https://kubernetes.io/docs/concepts/scheduling-eviction/eviction-policy/))
+
+- Execution engine was never deployed. Wether you're using [Jenkins](https://www.jenkins.io/)
+  or Wharf's own execution engine, if you never deployed it then no builds can
+  be started.
+
+- Execution engine is misconfigured and responded with a
+  [non-2xx status code.](https://en.wikipedia.org/wiki/List_of_HTTP_status_codes#2xx_success)
+
+- Network issues between the execution engine and the Wharf API processes.
+  Perhaps a misconfigured firewall or network policy.
+
+<!-- panels:end -->
+
+## Resolving it
+
+This is out of scope for any user that solely reaches either Wharf's web
+interface or REST API. Suggest you try to contact your
+administrator / operations team that manages your Wharf instance.
+
+If that fails, try promoting the issue over to the Wharf developers over at
+GitHub as an issue: <https://github.com/iver-wharf/wharf-api/issues/new>

docs/prob/api/provider/invalid-name.md

@@ -0,0 +1,55 @@
+# Problem: Invalid provider name
+
+<!-- panels:start -->
+
+<!-- div:right-panel -->
+
+- Title: `Invalid provider name.`
+- Type: `/prob/api/provider/invalid-name`
+
+<!-- div:left-panel -->
+
+Name of provider was not one of the supported/enabled providers.
+
+<!-- panels:end -->
+
+## Possible causes
+
+<!-- panels:start -->
+
+<!-- div:left-panel -->
+
+When a provider tries to register some projects but the name that the provider
+says it has is not in the valid set of provider names.
+
+At the time of writing (2021-05-19, with Wharf API v4.0.0 in development) it is
+still locked to only supporting a narrow set of provider names.
+
+<!-- div:right-panel -->
+
+:heavy_check_mark: Example valid inputs (as of Wharf API v4.0.0):
+
+- `github`
+- `gitlab`
+- `azuredevops`
+
+:x: Example invalid inputs:
+
+- ` ` *(empty value)*
+- `GitHub` *(must be lower-cased)*
+- `gitea` *(is not one of the above 3 valid provider names)*
+
+<!-- panels:end -->
+
+## Resolving it
+
+As a developer of the provider, you can make sure you are passing along one of
+the valid provider names listed above.
+
+If you are not a developer of the provider you are trying to use, then please
+report this issue to the developers. For the provider components developed by
+Iver you would create a new issue over at:
+
+- GitHub provider: <https://github.com/iver-wharf/wharf-provider-github/issues/new>
+- GitLab provider: <https://github.com/iver-wharf/wharf-provider-gitlab/issues/new>
+- Azure DevOps provider: <https://github.com/iver-wharf/wharf-provider-azuredevops/issues/new>