From b50468c16fd33d08e13a73759da08fda906584c5 Mon Sep 17 00:00:00 2001 From: Breezy <114720008+breezy-codes@users.noreply.github.com> Date: Fri, 25 Oct 2024 16:28:57 +1100 Subject: [PATCH] Spelling and Phrasing Updates --- .../Onboarding/01-setting-up.mdx | 58 +++---- .../Onboarding/03-pull-request.md | 145 +++++++++++++----- .../Onboarding/04-pull-request-template.md | 2 +- .../Onboarding/05-peer-review.md | 107 +++++++++---- 4 files changed, 214 insertions(+), 98 deletions(-) diff --git a/src/content/docs/products/splashkit/splashkit-website/Onboarding/01-setting-up.mdx b/src/content/docs/products/splashkit/splashkit-website/Onboarding/01-setting-up.mdx index 746b7f50..f4c16957 100644 --- a/src/content/docs/products/splashkit/splashkit-website/Onboarding/01-setting-up.mdx +++ b/src/content/docs/products/splashkit/splashkit-website/Onboarding/01-setting-up.mdx @@ -1,6 +1,6 @@ --- title: Get Started with Splashkit.io -description: This is a step-by-step guide on how to get started within the SplashKit Starlight Repo. +description: This is a step-by-step guide on how to get started within the SplashKit Starlight repo. sidebar: label: Getting Started with Splashkit.io order: 1 @@ -8,24 +8,24 @@ sidebar: import { Tabs, TabItem } from "@astrojs/starlight/components"; -## Get your Environment Set Up +## Get Your Environment Set Up -### Install necessary tools +### Install Necessary Tools -First things first, you'll need to install the necessary tools to get started working within Splashkit.io. -Head to the [Splashkit.io](https://splashkit.io/) website and follow the instructions for your specific -operating system to install splashkit. Then head to [Docker](https://docs.docker.com/engine/install/) +First things first, you'll need to install the necessary tools to get started working within SplashKit.io. +Head to the [SplashKit.io](https://splashkit.io/) website and follow the instructions for your specific +operating system to install SplashKit. Then, head to [Docker](https://docs.docker.com/engine/install/) and install Docker for your specific operating system. Finally, in your code editor of choice, ensure you have added the [Astro Extension](https://docs.astro.build/en/editor-setup/) to your editor. -### Fork the Splashkit.io Repo +### Fork the SplashKit.io Repo -To get started working within the Starlight.io you need to first head over to GitHub and make your -own fork of the [Splashkit Repo](https://github.com/thoth-tech/splashkit.io-starlight). +To get started working within the Starlight repo, you need to first head over to GitHub and make your +own fork of the [SplashKit Repo](https://github.com/thoth-tech/splashkit.io-starlight). ![splashkit repo](./images/starlightrepo.png) -Then select the fork button and create the fork: +Then, select the fork button and create the fork: ![splashkit fork](./images/splashkitfork.png) @@ -33,47 +33,47 @@ Then select the fork button and create the fork: -Head into the terminal within your machine and run the following commands, make sure to swap USERNAME -with your own username: +Open a terminal on your machine and run the following commands, making sure to replace `USERNAME` +with your own GitHub username: ```shell git clone https://github.com/USERNAME/splashkit.io-starlight.git ``` -Then navigate into the directory: +Then, navigate into the directory: ```shell cd splashkit.io-starlight git remote add upstream https://github.com/thoth-tech/splashkit.io-starlight.git ``` -Now you're all set up to start working on the Splashkit.io repo. +Now you're all set up to start working on the SplashKit.io repo. - -Open a new vscode window, and then open the command palette by pressing `cmd + shift + p`, then type -`git clone` and paste the URL of your forked repo. + +Open a new VSCode window, and then open the command palette by pressing `cmd + shift + p` (or `ctrl ++ shift + p` on Windows/Linux), then type `git clone` and paste the URL of your forked repo. ![splashkit repo](./images/gitclone.gif) -When prompted select the folder location you want to clone the repo into. +When prompted, select the folder location where you want to clone the repo. ![splashkit repo](./images/cloningrepo.png) -Once the repo is cloned, vscode will prompt you to open the repo folder location. +Once the repo is cloned, VSCode will prompt you to open the repo folder location. ![splashkit repo](./images/openrepo.png) -Now you're all set up to start working on the Splashkit.io repo in vscode. +Now you're all set up to start working on the SplashKit.io repo in VSCode. -Open up GitHub Desktop and click on the `File` tab in the top left corner, then select `Clone Repository`. +Open GitHub Desktop and click on the `File` tab in the top-left corner, then select `Clone Repository`. ![splashkit repo](./images/clonegitdesk.png) -Here you can either filter via your existing repositories or find the forked repo, or paste the URL +Here you can either filter via your existing repositories, find the forked repo, or paste the URL of the forked repo. ![splashkit repo](./images/cloneurlgitdesk.png) @@ -85,19 +85,19 @@ Once the repo is cloned, you can open the repo in your preferred code editor. ## Create Branches for Contributions -To start contributing to the Splashkit.io repo, you'll need to create a new branch for each contribution. +To start contributing to the SplashKit.io repo, you'll need to create a new branch for each contribution. ### Steps to Create a New Branch -Move into the Splashkit.io directory and create a new branch: +Move into the SplashKit.io directory and create a new branch: ```shell git checkout -b your-branch-name ``` -Then push the branch to your fork: +Then, push the branch to your fork: ```shell git push origin your-branch-name @@ -106,14 +106,14 @@ git push origin your-branch-name Now you're all set up to start working on your new branch. - + -Open source control by clicking on the icon on the left-hand side of the vscode window. Then select -on the three dots, go down to branch and select `Create Branch from`. +Open source control by clicking on the icon on the left-hand side of the VSCode window. Then click +on the three dots, go down to `Branch`, and select `Create Branch from`. ![splashkit repo](./images/newbranch-vscode.png) -Then select to make the new branch from `master` and name your branch. +Then, select to make the new branch from `master` and name your branch. ![splashkit repo](./images/addbranch-vscode.png) ![splashkit repo](./images/namebranch-vscode.png) diff --git a/src/content/docs/products/splashkit/splashkit-website/Onboarding/03-pull-request.md b/src/content/docs/products/splashkit/splashkit-website/Onboarding/03-pull-request.md index acec2483..17827c0a 100644 --- a/src/content/docs/products/splashkit/splashkit-website/Onboarding/03-pull-request.md +++ b/src/content/docs/products/splashkit/splashkit-website/Onboarding/03-pull-request.md @@ -1,6 +1,6 @@ --- title: How to Create a Pull Request -description: This is a step-by-step guide on how to create a pull request for SplashKit tutorials. +description: This is a step-by-step guide on how to create a pull request for SplashKit. sidebar: label: Pull Request Guide order: 3 @@ -8,20 +8,32 @@ sidebar: ## How to Create a Pull Request -Follow these steps to create a pull request for the SplashKit tutorials repository. +This guide provides a step-by-step process for creating a pull request (PR) in the SplashKit Starlight +repository, PRs are the primary way to contribute changes to the project. By following these steps, +you can submit your own PRs and collaborate with other team members effectively. ### 1. Check for Upstream Branches -First, check if the upstream branches are already added to your local repository. +Before creating a pull request, it's important to ensure that your local repository is connected to +the correct upstream repository. The upstream repository is the original repository from which your +fork was created. You need this connection to pull in the latest changes from the main project. + +To check if upstream branches are already linked to your local repository, run the following command: ```shell git remote -v ``` +This will display a list of remote repositories linked to your local repository. If the `upstream` +branch is not listed, you will need to add it in the next step. + ### 2. Add Upstream Branches (if not present) -If the upstream branches are not added, you can add them using the following command. Replace -`` with the actual repository name. +If the upstream branch is not already added, you can manually add it to your local repository. This +ensures you can fetch and merge changes from the main repository whenever necessary. + +To add the upstream branch, run the following command, replacing `` with the actual name +of the repository you're working with (e.g., `splashkit.io-starlight`). ```shell git remote add upstream https://github.com/thoth-tech/.git @@ -29,74 +41,133 @@ git remote add upstream https://github.com/thoth-tech/.git #### Example with `splashkit.io-starlight` Repository +For the `splashkit.io-starlight` repository, the command will look like this: + ```shell git remote add upstream https://github.com/thoth-tech/splashkit.io-starlight.git ``` ### 3. Verify Upstream Branches -Verify that the upstream branches have been added successfully. +After adding the upstream branch, verify that it has been added correctly by running the following +command again: ```shell git remote -v ``` +You should see something like this: + +```shell +origin https://github.com/YOUR-USERNAME/splashkit.io-starlight.git (fetch) +origin https://github.com/YOUR-USERNAME/splashkit.io-starlight.git (push) +upstream https://github.com/thoth-tech/splashkit.io-starlight.git (fetch) +upstream https://github.com/thoth-tech/splashkit.io-starlight.git (push) +``` + +If the upstream branch is correctly listed, you are now ready to create your pull request. + +## Sync Your Fork (Optional but Recommended) + +Before creating a pull request, it's good practice to sync your local fork with the upstream +repository to ensure you're working with the latest version. Run the following commands to fetch +and merge the latest changes from the upstream repository: + +```shell +git fetch upstream +git checkout main +git merge upstream/main +``` + +This ensures that your pull request will not conflict with the latest updates made by others. + ## Creating a Pull Request -To create a pull request, there are a few options available. You can use the GitHub website or the -[GitHub Pull Requests](https://marketplace.visualstudio.com/items?itemName=GitHub.vscode-pull-request-github) -extension in vscode. +There are two primary ways to create a pull request: using the GitHub website or the GitHub +Pull Requests extension in VSCode. -### Using GitHub Website +### Using the GitHub Website #### 1. Open GitHub to Review the Pull Request -Open GitHub and navigate to the repository where you want to create a pull request. Click on the -"Pull requests" tab and then click on the "New pull request" button. +Head to GitHub and navigate to your forked repository. Once there, click on the **Pull requests** +tab at the top of the page, and then click the **New pull request** button. ![pull request](./images/pull-request-fig1.png) -#### 2. Change to the Correct Repository +#### 2. Select the Correct Repository and Branches + +Next, make sure you're comparing the correct branches: -To ensure your pull request is directed to the correct repository, change the settings at the top of -the page. +- **Base Repository**: This should be set to `thoth-tech/splashkit.io-starlight` (the original +- repository you're contributing to). +- **Base Branch**: Select `main` as the branch to merge into. -- **Base Repository**: Set this to `thoth-tech/splashkit.io-starlight`. -- **Base Branch**: Set this to `main`. +The other dropdown should show your forked repository and the branch you want to merge from. ![pull request](./images/pull-request-fig2.png) -![pull request](./images/pull-request-fig3.png) +Ensure these settings are correct to avoid submitting changes to the wrong branch or repository. + +#### 3. Review Your Changes + +GitHub will display a comparison of the changes between your branch and the `main` branch of the +upstream repository. This is your opportunity to double-check the modifications you're proposing to merge. -#### 3. Add Pull Request Template +Make sure everything looks correct before proceeding. -Use the pull request template to provide detailed information about your request. Make sure to fill -out all necessary fields and complete any required checks. +#### 4. Add Pull Request Details + +When you create a pull request, you'll need to provide some additional information using a pull +request template. This helps reviewers understand the context of your changes. Make sure to: + +- Provide a clear and descriptive title for your pull request. +- Fill out the required fields in the template, such as the purpose of the changes, testing steps, + and any additional notes. ![pull request](./images/pull-request-fig4.png) -#### 4. Submit Your Pull Request +Be as detailed as possible. This makes it easier for reviewers to understand your contribution and +provide feedback. + +#### 5. Submit the Pull Request -After filling out the template and completing all required checks, submit your pull request for -review. +Once you've filled out the template and confirmed your changes, click the **Create pull request** +button. Your pull request will now be submitted and visible to the repository maintainers and +reviewers for feedback. -### Using GitHub Pull Requests Extension in vscode +### Using the GitHub Pull Requests Extension in VSCode -The steps here remain mostly the same as the prior steps, but you can do it all within vscode. -Head to the extension within the sidebar and click on the `Create Pull Request` button. This will -give you the option to select the branch you want to create the pull request from and the branch -you want to merge into. Follow the same steps as above to fill out the template and submit the pull -request. +Alternatively, you can use the [GitHub Pull Requests extension](https://marketplace.visualstudio.com/items?itemName=GitHub.vscode-pull-request-github) +for VSCode. This allows you to create pull requests directly from your code editor. + +#### 1. Open the Extension + +In VSCode, click on the GitHub Pull Requests icon in the sidebar. If you don't see it, you can +install it from the Extensions Marketplace. + +#### 2. Create the Pull Request + +Click the **Create Pull Request** button, which will give you the option to select the branch +you want to merge from (your working branch) and the branch you want to merge into (usually `main`). + +Follow the same steps as on the GitHub website to review your changes, fill out the pull request +template, and submit it. ![pull request](./images/prinvscode.gif) -### Next Steps +## Next Steps After Submitting a Pull Request + +Once your pull request is submitted, move the associated Planner card to the **First Peer Review** +column in your project management tool, and share both the pull request and the Planner card +with your team or peer reviewers. Follow the information on the[Planner Board Ettiquette](/products/splashkit/splashkit-website/onboarding/07-planner-board) +page to ensure a smooth review process. + +Keep an eye out for feedback from the reviewer, and be prepared to make changes if necessary. -Once the pull request is submitted, move the associated Planner card to the "First Peer Review" column -and share the pull request and card in the group chat. well done! Now, keep an eye out for feedback -from your peer reviewer. +### Useful Links - [Pull Request Template](/products/splashkit/splashkit-website/onboarding/04-pull-request-template): - The template for creating a pull request for SplashKit tutorials. -- [Peer Review Guide](/products/splashkit/splashkit-website/onboarding/05-peer-review): The guide - on how to do a peer review within the SplashKit tutorials team. + The template for creating a pull request for SplashKit team. +- [Peer Review Guide](/products/splashkit/splashkit-website/onboarding/05-peer-review): + The guide on how to perform a peer review within the SplashKit team. diff --git a/src/content/docs/products/splashkit/splashkit-website/Onboarding/04-pull-request-template.md b/src/content/docs/products/splashkit/splashkit-website/Onboarding/04-pull-request-template.md index 344f743b..4a18cfac 100644 --- a/src/content/docs/products/splashkit/splashkit-website/Onboarding/04-pull-request-template.md +++ b/src/content/docs/products/splashkit/splashkit-website/Onboarding/04-pull-request-template.md @@ -1,6 +1,6 @@ --- title: Pull Request Template -description: This is a template for creating a pull request for SplashKit tutorials. +description: This is a template for creating a pull request for SplashKit Website. sidebar: label: Pull Request Template order: 4 diff --git a/src/content/docs/products/splashkit/splashkit-website/Onboarding/05-peer-review.md b/src/content/docs/products/splashkit/splashkit-website/Onboarding/05-peer-review.md index bbb939ec..f8337c7f 100644 --- a/src/content/docs/products/splashkit/splashkit-website/Onboarding/05-peer-review.md +++ b/src/content/docs/products/splashkit/splashkit-website/Onboarding/05-peer-review.md @@ -1,35 +1,44 @@ --- title: A Guide to Doing Peer Reviews -description: A guide on how to do a peer review within the SplashKit tutorials team. +description: A guide on how to do a peer review within the SplashKit team. sidebar: label: Peer Review Guide order: 5 --- -This guide will help you through the process of performing a peer review for SplashKit tutorials. +This guide will walk you through the process of performing a peer review for the SplashKit Starlight +project, detailing each step to help you provide thorough and constructive feedback on a pull request +(PR). ## How to Perform a Peer Review -Follow these steps to review a pull request (PR) in the SplashKit tutorials repository. +To maintain code quality and ensure smooth integration of new features, it’s essential to follow +these steps when reviewing a PR in the SplashKit Starlight repository. ### 1. Check for Upstream Branches -First, verify if the upstream branches are already added to your local repository. +Start by verifying whether the upstream branches are already added to your local repository. This is +necessary to ensure that you can fetch PRs from the original repository for review. ```shell git remote -v ``` +If the output does not show `upstream` linked to the main repository, you’ll need to add it in the +next step. + ### 2. Add Upstream Branches (if not present) -If the upstream branches are not added, you can add them using the following command. Replace -`` with the actual repository name. +If the upstream branch is missing, add it manually. Replace `` with the exact name of +the repository. ```shell git remote add upstream https://github.com/thoth-tech/.git ``` -#### Example with `splashkit.io-starlight` Repository +#### Example: Adding the `splashkit.io-starlight` Repository + +For the `splashkit.io-starlight` repository, the command will be: ```shell git remote add upstream https://github.com/thoth-tech/splashkit.io-starlight.git @@ -37,31 +46,33 @@ git remote add upstream https://github.com/thoth-tech/splashkit.io-starlight.git ### 3. Verify Upstream Branches -Verify that the upstream branches have been added successfully. +Confirm that the upstream branch has been added correctly by running: ```shell git remote -v ``` +You should see both `origin` (your fork) and `upstream` (the main project repository) listed. + ### 4. Pull the PR into a New Branch -To review a pull request, you need to fetch it into a new branch. Check the ID/number of the PR you -want to review. Use the following command to fetch the PR, replacing `ID` with the PR number and -`PR-branch-name` with a name you want to use for this review. +To review a PR, you will fetch it into a new local branch. Locate the ID/number of the PR on GitHub, +and use this number in the following command. Replace `ID` with the PR number and `PR-branch-name` +with a name that represents the PR purpose. ```shell git fetch upstream pull/ID/head:PR-branch-name ``` -#### Example: If Testing PR#7 that Adds "xyz" Feature +#### Example: Fetching PR #7 that Adds a "New Feature" ```shell -git fetch upstream pull/7/head:test-feature-xyz +git fetch upstream pull/7/head:test-new-feature ``` ### 5. Checkout the New Branch -Switch to the new PR testing branch. +Switch to the newly created branch to start reviewing the PR. ```shell git checkout PR-branch-name @@ -69,19 +80,28 @@ git checkout PR-branch-name ### 6. Review the Code -Now that you have the PR branch checked out, you can review the code. Look for the following -aspects: +Now that you are on the PR branch, start by reviewing the code to check for: + +- **Code Quality**: Confirm that the code aligns with the project’s coding standards and guidelines. + Look for clean, well-organised, and readable code. +- **Functionality**: Verify that the changes achieve the intended purpose and work as described. +- **Testing**: Check for the presence of adequate tests, including unit and integration tests where necessary. +- **Documentation**: Ensure any new features or updates are documented, with clear comments for + any complex sections. -- **Code Quality**: Ensure the code follows the project's coding standards and guidelines. -- **Functionality**: Verify that the new feature or bug fix works as intended. -- **Testing**: Check if there are adequate tests and if they pass successfully. -- **Documentation**: Ensure that any new features or changes are well-documented. +Refer to the pull request template as you go through these checks to confirm that all required +fields are covered. -#### Refer back to the checks in the pull request template +#### Reference Checklist from Pull Request Template -This is also shown below to ensure you have covered all the necessary aspects +Use this checklist as a reference to ensure you’re covering all necessary areas in your review. ```markdown +# Description + +Please include a summary of the changes and the related issue. Please also include relevant +motivation and context. List any dependencies that are required for this change. + ## Type of change - [ ] Bug fix (non-breaking change which fixes an issue) @@ -129,20 +149,45 @@ Please list the folders and files added/modified with this pull request. - Modified: - [ ] folder/file - [ ] folder/file + +## Additional Notes + +Please add any additional information that might be useful for the reviewers. ``` -### 7. Test the Changes +### 7. Test the Changes Locally -Run the project locally to test the changes introduced by the PR. Make sure everything works as -expected and there are no new bugs introduced. +After the code review, run the project locally to verify that the new feature or bug fix works +as expected. This can include: -### 8. Provide Feedback +- Running any test suites that come with the project. +- Manually checking if the new functionality behaves correctly and does not introduce any bugs. +- Ensuring the changes do not break other parts of the project. -After reviewing and testing, provide constructive feedback on the PR. You can add comments directly -on the PR in GitHub. Mention any required changes or improvements. +### 8. Provide Constructive Feedback + +After reviewing and testing, leave constructive feedback directly on the PR on GitHub. Highlight +both positive aspects and areas for improvement. + +- Use specific comments on code lines or sections where changes are required. +- Make sure to explain why a change is needed to help the author learn and understand. +- Be courteous and professional, focusing on improving the code and maintaining high project standards. ### 9. Approve or Request Changes -Based on your review, either approve the PR or request changes. If everything looks good and works -as expected, you can approve the PR. If there are issues, request changes and provide detailed -feedback. +Once you’ve completed your review: + +- **Approve** if everything meets the project’s standards and the code works as expected. +- **Request Changes** if the code requires adjustments before it can be merged. Clearly outline + the changes required. + +In both cases, document your decision and leave detailed notes to assist the author. + +### 10. Update Planner Board Status + +Following the [Planner Board Etiquette](/products/splashkit/splashkit-website/onboarding/07-planner-board), +move the associated Planner card to the next column based on the review outcome. If the PR is approved, +update the card’s status accordingly, and if you requested changes, mark it for revision. + +By following this guide, you’ll ensure a thorough and professional review process, helping maintain +the quality and reliability of the SplashKit Starlight project.