diff --git a/documentation/assets/images/codespaces_steps_001.png b/documentation/assets/images/codespaces_steps_001.png new file mode 100644 index 0000000000..0703be31bc Binary files /dev/null and b/documentation/assets/images/codespaces_steps_001.png differ diff --git a/documentation/assets/images/codespaces_steps_002.png b/documentation/assets/images/codespaces_steps_002.png new file mode 100644 index 0000000000..2c8b08c4a9 Binary files /dev/null and b/documentation/assets/images/codespaces_steps_002.png differ diff --git a/documentation/assets/images/codespaces_steps_003.png b/documentation/assets/images/codespaces_steps_003.png new file mode 100644 index 0000000000..b211d1eafb Binary files /dev/null and b/documentation/assets/images/codespaces_steps_003.png differ diff --git a/documentation/assets/images/codespaces_steps_004.png b/documentation/assets/images/codespaces_steps_004.png new file mode 100644 index 0000000000..4aac22bf7f Binary files /dev/null and b/documentation/assets/images/codespaces_steps_004.png differ diff --git a/documentation/assets/images/codespaces_steps_005.png b/documentation/assets/images/codespaces_steps_005.png new file mode 100644 index 0000000000..50fae869eb Binary files /dev/null and b/documentation/assets/images/codespaces_steps_005.png differ diff --git a/documentation/assets/images/codespaces_steps_006.png b/documentation/assets/images/codespaces_steps_006.png new file mode 100644 index 0000000000..a620d0f3f5 Binary files /dev/null and b/documentation/assets/images/codespaces_steps_006.png differ diff --git a/documentation/assets/images/codespaces_steps_007.png b/documentation/assets/images/codespaces_steps_007.png new file mode 100644 index 0000000000..2a63e9cd56 Binary files /dev/null and b/documentation/assets/images/codespaces_steps_007.png differ diff --git a/documentation/assets/images/codespaces_steps_008.png b/documentation/assets/images/codespaces_steps_008.png new file mode 100644 index 0000000000..a08f50a14c Binary files /dev/null and b/documentation/assets/images/codespaces_steps_008.png differ diff --git a/documentation/assets/images/codespaces_steps_009.png b/documentation/assets/images/codespaces_steps_009.png new file mode 100644 index 0000000000..817b992a44 Binary files /dev/null and b/documentation/assets/images/codespaces_steps_009.png differ diff --git a/documentation/assets/images/codespaces_steps_010.png b/documentation/assets/images/codespaces_steps_010.png new file mode 100644 index 0000000000..b6539404c2 Binary files /dev/null and b/documentation/assets/images/codespaces_steps_010.png differ diff --git a/documentation/assets/images/codespaces_steps_011.png b/documentation/assets/images/codespaces_steps_011.png new file mode 100644 index 0000000000..05b17e645a Binary files /dev/null and b/documentation/assets/images/codespaces_steps_011.png differ diff --git a/documentation/assets/images/codespaces_steps_012.png b/documentation/assets/images/codespaces_steps_012.png new file mode 100644 index 0000000000..1b6dc44d4b Binary files /dev/null and b/documentation/assets/images/codespaces_steps_012.png differ diff --git a/documentation/assets/images/codespaces_steps_013.png b/documentation/assets/images/codespaces_steps_013.png new file mode 100644 index 0000000000..fe199fa5c8 Binary files /dev/null and b/documentation/assets/images/codespaces_steps_013.png differ diff --git a/documentation/assets/images/codespaces_steps_014.png b/documentation/assets/images/codespaces_steps_014.png new file mode 100644 index 0000000000..584f7edbae Binary files /dev/null and b/documentation/assets/images/codespaces_steps_014.png differ diff --git a/documentation/assets/images/codespaces_steps_015.png b/documentation/assets/images/codespaces_steps_015.png new file mode 100644 index 0000000000..08eba46332 Binary files /dev/null and b/documentation/assets/images/codespaces_steps_015.png differ diff --git a/documentation/assets/images/codespaces_steps_016.png b/documentation/assets/images/codespaces_steps_016.png new file mode 100644 index 0000000000..1e3f55d331 Binary files /dev/null and b/documentation/assets/images/codespaces_steps_016.png differ diff --git a/documentation/reference/how-to-contribute-using-codespace.en.md b/documentation/reference/how-to-contribute-using-codespace.en.md new file mode 100644 index 0000000000..677ed6c962 --- /dev/null +++ b/documentation/reference/how-to-contribute-using-codespace.en.md @@ -0,0 +1,213 @@ +--- +title: QField Documentation Contribution +tx_slug: documentation_get-started_how-to-contribute-using-codespaces +--- + +# Contributing to the Documentation Using GitHub Codespaces + +You can contribute to the QField documentation by making improvements, correcting spelling and grammar, or adding new information. +This guide provides a workflow that doesn't require installing anything on your local machine. +All you need is a web browser and a free GitHub account. + +We will use GitHub Codespaces, an online development environment that automatically sets up all the necessary tools for you. + +## Step-by-Step Guide + +### 1. Create a New Branch + +First, you need to create a personal branch where you will make your changes. +A branch isolates your work from the main codebase until it's ready to be merged to the master branch. + +1. Navigate to the official [QField Docs repository](https://github.com/opengisch/QField-docs). + +2. Click on the branch dropdown, which likely shows `master`. + +3. In the text box, type a descriptive name for your new branch. +Branch names should not contain spaces; use underscores (`_`) or hyphens (`-`) instead. For example: `fix_welcome_page_typos`. + +4. Click on **"Create branch: `` from `master`"**. +GitHub will automatically create the branch and switch to it. + +!![](../assets/images/codespaces_steps_001.png,850px) + +### 2. Launch the Codespace + +Now, launch the cloud-based editor for your new branch. + +1. Click the green **`Code`** button. + +2. Select the **"Codespaces"** tab. + +3. Click the **"Create codespace on ``"** button. + +!![](../assets/images/codespaces_steps_002.png,850px) + +GitHub will now prepare your Codespace. +This may take a few minutes as it installs all the required dependencies in the background. + +### 3. (Optional) Set Up the 'Doc Writer' Profile + +To enhance your writing experience, you can activate a pre-configured profile that installs helpful extensions for writing documentation. + +1. Once the Codespace has loaded, click the **Gear icon** (`⚙️`) in the bottom-left corner. + +2. Select **Profiles > New Profile**. + +!![](../assets/images/codespaces_steps_003.png,850px) + +3. In the "Copy from..." dropdown, select **"Doc Writer"** and click **Create**. + +!![](../assets/images/codespaces_steps_004.png,850px) + +4. If a pop-up appears asking for trust, click **"Trust Publisher and Install"**. + +!![](../assets/images/codespaces_steps_005.png,850px) + +### 4. Find and Edit Files + +You are now ready to make your changes. + +- The documentation source files are located in the `documentation/` directory in the file explorer panel on the left. + +- You will primarily edit the Markdown (`.md`) files within the `get-started/`, `how-to/`, and `reference/` subdirectories. + +- Place any new or edited images or videos in the `documentation/assets/images/` or `documentation/assets/videos/` folders, respectively, +by drag and drop the files directly on the directory file explorer panel. + +To see a live preview of your changes, right-click the file tab of the document you are editing and select **"Open Preview"** (or use the shortcut `Ctrl+Shift+V`). +You can drag this preview tab to the side to see your edits update in real-time. + +!![](../assets/images/codespaces_steps_006.png,850px) + +!![](../assets/images/codespaces_steps_007.png,850px) + +Please ensure your contributions adhere to the writing style and formatting conventions of [MkDocs](https://www.mkdocs.org/user-guide/writing-your-docs/) and [MkDocs Material](https://squidfunk.github.io/mkdocs-material/reference/). + +### 5. Run a Local Preview Server + +To see how your changes will look on the final documentation website, you can run a local server within your Codespace. + +1. Open a new terminal by going to the top menu and selecting **Terminal > New Terminal**. + +2. Run the following commands: + + ```bash + export BUILD_ONLY_LOCALE="en" + python3 -m mkdocs serve + ``` + +!![](../assets/images/codespaces_steps_008.png,850px) + +3. A notification will appear in the bottom-right corner. +Click **"Open in Browser"** to view the live documentation site. +The page will automatically reload whenever you save a file. + +!![](../assets/images/codespaces_steps_009.png,850px) + +!![](../assets/images/codespaces_steps_010.png,850px) + +### 6. Save Your Work (Commit and Push) + +Once you are satisfied with your changes, you need to save them to Git and push them to GitHub. + +A. Stage Your Changes + +Stage all modified files, preparing them for a commit. +You can do this using the integrated terminal: + +```bash +git add . +``` + +Alternatively, go to the **"Source Control"** tab (the icon with three connected dots) +(or by using the Shortcut `CTRL+Shift+G`) on the left sidebar and click the `+` icon next to each file or next to the "Changes" heading. + +!![](../assets/images/codespaces_steps_011.png,850px) + +B. Run Pre-Commit Checks + +We use a tool called pre-commit to automatically check your files for formatting errors, broken links, and other common issues. +This helps maintain code quality and avoids errors. + +Run it from the terminal: + +```bash +pre-commit run +``` + +If the tool reports any errors, it may fix them automatically. +In that case, you will need to **stage the changes again** (`git add .`). +If it reports errors it cannot fix, please correct them manually and then run the command again until all checks show as **"Passed"** in green. + +!![](../assets/images/codespaces_steps_012.png,850px) + +- Is pre-commit not installed? + +The Codespace environment should install pre-commit automatically. +If you see a "Bash command not found" error, you can install it manually by running: + +```bash +python3 -m pip install pre-commit +``` + +C. Commit Your Changes + +A commit is a snapshot of your staged changes. +Each commit has a message describing the work you did. + +In the terminal, run: + +```bash +git commit -m "Your descriptive message here" +``` + +Example: git commit -m "Fix typos on the Welcome Page" + +Alternatively, use the Source Control tab: type your message in the text box at the top and click the "Commit" button. + +!![](../assets/images/codespaces_steps_013.png,850px) + +D. Push Changes to GitHub + +Push your commit from the Codespace to your branch on GitHub. + +In the terminal, run: + +```bash +git push +``` + +Or, in the Source Control tab, click the **"Sync Changes"** button. + +!![](../assets/images/codespaces_steps_014.png,850px) + +### 7. Create a Pull Request + +The final step is to create a Pull Request (PR), which is a formal request to merge your changes into the main `master` branch. + +1. Go back to the [QField Docs repository page](https://github.com/opengisch/QField-docs) on GitHub. + +2. You should see a yellow banner with your branch name. +Click the **"Compare & pull request"** button. + +3. Give your Pull Request a descriptive title and write a brief summary of the changes you made in the description box. + +4. Click **"Create pull request"**. + +!![](../assets/images/codespaces_steps_015.png,850px) + +!![](../assets/images/codespaces_steps_016.png,850px) + +### 8. Address Review Feedback + +A maintainer will review your contribution. +If they request changes, you can easily make updates: + +1. Re-open your Codespace for that branch (you can find it in the "Codespaces" tab of the repository). + +2. Make the requested edits. + +3. Follow [**Step 6**](#6-save-your-work-commit-and-push) again to stage, run pre-commit, commit, and push your new changes. +The Pull Request will update automatically. + +Thank you for contributing to the QField documentation! diff --git a/mkdocs.yml b/mkdocs.yml index f71feb684c..29e5fd7d6e 100644 --- a/mkdocs.yml +++ b/mkdocs.yml @@ -96,6 +96,7 @@ nav: - how-to/processing.md - Technical reference: - reference/index.md + - reference/how-to-contribute-using-codespace.md - reference/data-format.md - reference/exif.md - reference/expression_variables.md