Merge branch '406-maintainer-documentation' into 'main'

docs: maintainer documentation

See merge request gitlab-org/gitlab-vscode-extension!281

CONTRIBUTING.md

@@ -39,7 +39,7 @@ Create a [new issue from the "Feature Proposal" template](https://gitlab.com/git
 
 ### Your First Code Contribution?
 
-Read about the extension architecture in [architecture.md](docs/architecture.md). This document explains how we structure our code and will help you orientate yourself in the codebase.
+Read about the extension architecture in [architecture.md](docs/developer/architecture.md). This document explains how we structure our code and will help you orientate yourself in the codebase.
 
 For newcomers to the project, you can take a look at issues labelled as `Accepting merge requests`
 as available [here](https://gitlab.com/gitlab-org/gitlab-vscode-extension/-/issues?label_name[]=Accepting%20merge%20requests).
@@ -50,7 +50,7 @@ For general information how to develop and debug VS Code Extensions, please see
 
 The following instructions will help you run the GitLab Workflow Extension locally.
 
-Please review our [Coding guidelines](docs/coding-guidelines.md) before writing new code.
+Please review our [Coding guidelines](docs/developer/coding-guidelines.md) before writing new code.
 
 #### Step - 1 : Installation Prerequisites
 
@@ -111,7 +111,7 @@ To run tests, open terminal within the project folder and run following:
 npm test
 ```
 
-See also [how to write automated tests](docs/writing-tests.md).
+See also [how to write automated tests](docs/developer/writing-tests.md).
 
 #### Step - 7 : Run linter
 
@@ -128,4 +128,4 @@ Steps to opening a merge request to contribute code to GitLab Workflow is simila
 You develop in a separate branch of your own fork and the merge request should have a related issue open in the project.
 Any Merge Request you wish to open in order to contribute to GitLab Workflow, be sure you have followed through the steps from [Configuring Development Environment](#configuring-development-environment).
 
-In this project, we don't [close issues automatically when the MR gets merged](https://docs.gitlab.com/ee/user/project/issues/managing_issues.html#closing-issues-automatically). Instead, we close the issues when the MR change is [released](docs/release-process.md). Please replace `Closes #<issueId>` in the MR description with `Relates to #<issueId>`.
+In this project, we don't [close issues automatically when the MR gets merged](https://docs.gitlab.com/ee/user/project/issues/managing_issues.html#closing-issues-automatically). Instead, we close the issues when the MR change is [released](docs/developer/release-process.md). Please replace `Closes #<issueId>` in the MR description with `Relates to #<issueId>`.

docs/developer/maintainer.md

+# Maintainer documentation
+
+This document is for new extension maintainers.
+
+## Access you need
+
+- Maintainer access to [`gitlab-org/gitlab-vscode-extension`](https://gitlab.com/gitlab-org/gitlab-vscode-extension)
+- Access to "VS Code Extension" 1Password vault
+
+With this access you should be able to [release the extension](release-process.md).
+

docs/developer/release-process.md

+# Release process
+
+You need to perform the following steps to release a new version of the extension.
+These examples use version `3.0.0`:
+
+1. Do a quick test of the extension in your local development. At this stage, you
+   are only verifying there is no complete failure of the extension.
+1. Update the package version in `npm version 3.0.0`. This automatically generates a changelog entry.
+1. If there have been community contributions:
+   1. Manually add attribution to the `CHANGELOG.md` and `CONTRIBUTORS.md`. For example:
+
+      ```plaintext
+      (Implemented|Fixed) by [@flood4life](https://gitlab.com/flood4life) with [MR !90](https://gitlab.com/gitlab-org/gitlab-vscode-extension/-/merge_requests/90) 👍
+      ```
+
+   1. Add the contributor's entry to `CONTRIBUTORS.md`, if it doesn't exist.
+1. `git push origin main` and `git push --tags`
+1. Trigger the **Publish** step on the tag pipeline.
+1. When the extension updates in your VS Code, do another quick check.
+
+## Access tokens for Marketplaces
+
+*This section applies once a year when the Microsoft VS Code Marketplace token automatically expires.*
+
+Our [CI jobs](https://gitlab.com/gitlab-org/gitlab-vscode-extension/blob/e80e5798dbac5944ebaa52dc0dc2cb861509588e/.gitlab-ci.yml#L110-124) use the access tokens for publishing packaged extension to market places.
+
+### How to generate tokens
+
+#### Open VSX
+
+1. Log in to [github.com](https://github.com/) with `GitHub vscode account`
+   credentials from the "VS Code Extension" 1Password Vault.
+1. Log in to [open-vsx.org](https://open-vsx.org/) with the GitHub account.
+1. Go to the [Access Tokens Settings page](https://open-vsx.org/user-settings/tokens).
+1. Create a new token.
+
+#### Microsoft VS Code Marketplace
+
+1. Sign in to [Microsoft Azure](https://azure.microsoft.com/) with `VScode Marketplace`
+   credentials from the "VS Code Extension" 1Password Vault.
+1. Go to **Personal Access Tokens**.
+   ([Official VS Code publishing documentation](https://code.visualstudio.com/api/working-with-extensions/publishing-extension#get-a-personal-access-token)).
+1. You can either:
+   - Extend the expiration date of an existing token. **This is the best solution when you receive token expiration email.**
+   - Generate a new token. Assign it the least privileges possible - it probably only
+     needs **Marketplace - publish**.

docs/release-process.md

-# Release process
-
-You need to perform the following steps to release a new version of the extension (examples use `3.0.0` version):
-
-1. Do "sanity check" testing of the extension in your local development. At this stage, you are only making sure that there is no complete failure of the extension.
-1. Update the package version in `npm version 3.0.0` (this automatically generates a changelog)
-1. If there have been community contributions, manually add attribution to the `CHANGELOG.md` and `CONTRIBUTORS.md`
-   - Example: `(Implemented|Fixed) by [@flood4life](https://gitlab.com/flood4life) with [MR !90](https://gitlab.com/gitlab-org/gitlab-vscode-extension/-/merge_requests/90) 👍`
-   - Add contributor's entry to `CONTRIBUTORS.md` if it doesn't exist
-1. `git push origin main` and `git push --tags`
-1. Trigger the "publish" step on the tag pipeline.
-1. When the extension updates in your VS Code, do another sanity check.

scripts/commit-lint/lint.js

@@ -15,7 +15,7 @@ const {
 } = process.env;
 
 const urlSemanticRelease =
-  'https://gitlab.com/gitlab-org/gitlab-vscode-extension/-/blob/main/docs/commits.md';
+  'https://gitlab.com/gitlab-org/gitlab-vscode-extension/-/blob/main/docs/developer/commits.md';
 
 const customRules = {
   'header-max-length': [2, 'always', maximumLineLength],

scripts/update_ci_variables.js

@@ -60,7 +60,7 @@ async function run() {
 
   if (process.env.CI && onlineVariablesJson !== existingVariablesJson) {
     console.error(
-      '❌ ./src/utils/ci_variables.json has changed, go to https://gitlab.com/gitlab-org/gitlab-vscode-extension/-/blob/main/docs/ci-variables.md.',
+      '❌ ./src/utils/ci_variables.json has changed, go to https://gitlab.com/gitlab-org/gitlab-vscode-extension/-/blob/main/docs/developer/ci-variables.md.',
     );
     process.exit(1);
   }

test/integration/test_infrastructure/validate_test_environment.js

@@ -5,7 +5,7 @@ const validateTestEnvironment = () => {
     throw new Error(`
     Your test workspace is not properly setup!
     Please run "npm run create-test-workspace". You can also read the docs at:
-    https://gitlab.com/gitlab-org/gitlab-vscode-extension/-/blob/main/docs/writing-tests.md#debugging-integration-tests
+    https://gitlab.com/gitlab-org/gitlab-vscode-extension/-/blob/main/docs/developer/writing-tests.md#debugging-integration-tests
     `);
   }
 };