documentation/How-to-develop-on-the-website.md

-> To follow this documentation you should [set up a local copy of the website](Compiling-a-local-version-of-the-website) first.
+Each website can be a little different but there are a few rules that are
+standard. Some of these rules are imposed by the static website generator that
+we use (Lektor). Other rules are made up by the web team to make development
+easier.
 
-Each website can be a little different but there are a few rules that are standard. Some of these rules are imposed by the static website generator that we use (Lektor). Other rules are made up by the www team to make development easier.
+### Development environment
+
+There are two ways to develop on the websites: using GitLab or building locally.
+
+#### GitLab
+
+Most users should use GitLab to make website edits and author new pages,
+followed by a merge request.
+
+The procedure differs based on whether you're granted the `Developer` role on
+the website project you want to edit:
+
+  - Regular contributors to web projects may request this privilege by
+    [opening a ticket](https://gitlab.torproject.org/tpo/tpa/team/-/issues/new)
+
+  - Occasional or "drive-by" contributors may still submit edits without this
+    role
+
+The instructions below will get you started making edits, viewing previews
+built in CI and submitting a merge request.
+
+Once the merge request is reviewed and accepted by a project maintainer, a full
+project build will automatically be triggered and deployed to
+`https://<projectname>.staging.torproject.org`.
+
+If the staging build passes QA, a deployment to production must be triggered
+manually via the `Pipelines` or `Environments` project subpages. This is
+usually done by another member of the project, but in the case of trivial
+changes, the `deploy-prod` may be triggered by the merge request author.
+
+If you need assistance, don't hesitate to drop by on
+[IRC](https://gitlab.torproject.org/tpo/tpa/team/-/wikis/support#quick-question-chat)
+in channel `#tor-www` or
+[open a ticket](https://gitlab.torproject.org/tpo/tpa/team/-/wikis/support#bug-reports-feature-requests-and-others-issue-tracker).
+
+##### Without Developer role
+
+  1. Go to the GitLab project page and create a personal fork using the Fork
+     button, this will create a copy of the project in your GitLab user's
+     namespace
+
+  2. On the forked project's page, click the `Web IDE` button to load the
+     web-based project editor
+
+  3. In this environment you can make any changes like creating and modifying
+     the project's files
+
+  4. When finished, click the `Source Control` tab on the left side of the
+     page, enter a commit message and click `Commit & Push`
+
+  5. A preview build will be then triggered in CI; its progress can be
+     followed on the project's `CI/CD` / `Pipelines` page
+
+  6. Ensure the pipeline's jobs succeed, otherwise the preview build will not
+     be available; in case of failure the cause must be identified and fixed
+     using the failing job's log
+
+  7. When successful, the preview build will be uploaded to GitLab pages at
+     `https://<username>.pages.torproject.net/<projetname>`, which means if
+     your username is `foo` and the project name is `blog`, the preview can be
+     accessed at `https://foo.pages.torproject.net/blog`
+
+  8. Additional changes/commits may be implemented by repeating steps 2 to 7
+
+  9. Once the changeset is ready for inclusion in the main project, click the
+     `Create merge request` button on your project's main page, enter a title
+     and description and click the blue `Create merge request` button
+
+  10. A project maintainer will receive a notification and review your merge
+      request
+
+##### With Developer role
+
+  1. Navigate to the project's GitLab page
+
+  2. Navigate to `Repository` ➡ `Branches` via the left-hand menu and click
+     `New branch`, then pick a descriptive name making sure `Create from` is
+     set to `main`
+
+  3. Click the `Web IDE` button just above the file listing
+
+  4. In this environment you can make any changes like creating and modifying
+     the project's files
+
+  5. When finished, click the `Source Control` tab on the left side of the
+     page, enter a commit message and click `Commit & Push`
+
+  6. Click `Create MR` in the dialog that appears in the bottom right; enter a
+     title and description and click the blue `Create merge request` button
+
+  7. A preview build will be then triggered in CI; its progress can be
+     followed on the project's `CI/CD` / `Pipelines` page
+
+  8. Ensure the pipeline's jobs succeed, otherwise the preview build will not
+     be available; in case of failure the cause must be identified and fixed
+     using the failing job's log
+
+  9. Once the initial build is successful, a `View app` button will appear on
+     the merge request page, click it to navigate to the build preview
+
+  10. Additional changes/commits may be implemented by repeating steps 3 to 5
+
+  11. Once the changeset is ready for inclusion in the main project, click the
+      `Mark as ready` button on the merge request page
+
+  12. A project maintainer will receive a notification and review your merge
+      request
+
+This process, applied to the blog project, is described in more detail on the
+TPA wiki at
+[service/blog](https://gitlab.torproject.org/tpo/tpa/team/-/wikis/service/blog#how-to-write-a-new-blog-post-in-gitlab)
+
+#### Building locally
+
+Users who are comfortable on the command-line and with `git` may prefer to
+install a development environment on their local computer instead of using
+GitLab. The instructions for doing can be found on this page:
+[Compiling a local version of the website](documentation/Compiling-a-local-version-of-the-website).
 
 ### Lego