Instructions for contributing to Stitch Docs.

Prerequisites

• You have installed a code editor, such as VSCode or Sublime Text.

• You have cloned the Stitch Docs repository. To be able to create a branch and merge your changes to master, you should be in the Tech Docs team.

Step 1: Create a new branch

To edit Stitch Docs, you first need to create a new branch in the repository. If you are using GitHub Desktop:

1. Click Branch>New branch.
2. Enter a name for your branch.
3. Make sure to create the branch from master.
4. Click Create branch.

If you are using a command line, make sure you are on the master branch and use the following command:

git branch your_branch_name

Once the branch is created, you can start editing content.

Step 2: Commit and push changes

Once you have made your changes to the Stitch Docs, you can commit and push them. If you are using GitHub Desktop:

1. Click Fetch origin to make sure your branch is up to date.
2. In the Summary field, enter a commit message.
3. Click Commit.
4. Click Push origin.

If you are using a command line:

1. Pull the latest updates on the branch with git pull.
2. Stage your changes with git add. To add all modified files, use git add -A, otherwise, use git add file_name.
3. Commit your changes with git commit -m "commit message".
4. Push your changes with git push.

Step 3: Create a pull request

If you go to the repository on GitHub after pushing your changes, you should see a message that looks like this:

1. Click Compare & pull request.
2. Enter a title and a description if needed, then click Create pull request.

The pull request is created and the checks start running.

Step 4: Preview your changes

Once a pull request is created on the stitch-docs repository, a Netlify action runs to publish a preview of your changes. To access it:

1. Open your PR on GitHub, scroll down to the section about checks and click Show all checks.
2. Click Details next to the deploy/netlify. You will get a Page Not Found, this is a known issue.
3. To access the preview, add /docs at the end of the URL.

Step 5: Merge a pull request

Once all checks have passed and the content you added is validated, you can merge your PR. If you are an administrator of the repository, you can merge without a review.

Note: Once a pull request is merged to master, Netlify automatically redeploys the site, so make sure that everything is in a publishable state before merging.

1. Click Squash and merge or Merge pull request.

   The Squash and merge option creates a single commit from the changes in the source branch, while the Merge pull request options adds all individual commits to the target branch.

2. If the pull request has no reviews, select the Use your adminitrator privileges to merge this pull request check box and click Confirm merge.

Step 6: Follow the Netlify deployment

After merging your PR, you can go to Netlify to follow the deployment of the Stitch Docs site.

1. Go to the Stitch Docs overview on Netlify.
2. In the Production deploys section, click the deployment that matches your PR.

In the Deploy log, you can see the status of the deployment. Once it is finished, you can check your changes on Stitch Docs.

Last updated: 22 February 2022