Making changes

To submit changes to the SDK docs repository, you need the following tools installed on your machine:

• Git: a distributed version control system
• Docker: a service for managing containerized services
• Visual Studio Code: an extensible code editor
• Vale: a configurable style guide checker

This guide targets macOS users, but the same steps apply to all platforms.

• Setup
  • 1. Install Homebrew
  • 2. Install Git
  • 3. Install Vale
  • 4. Install Visual Studio Code
  • 5. Set up an SSH key
  • 6. Clone the repository
• Using Git
  • Branches
  • Stages
• Editing the docs
  • 1. Open the repo in VS Code
  • 2. Install extensions
  • 3. Start the Docker preview
  • 4. Create a new branch
  • 5. Edit the docs
  • 6. Use the source control menu to manage changes
    • Staging changes
    • Make a commit
    • Push changes
  • 7. Open a pull request
    • In VS Code

Setup

Follow these steps to set up the repository on your machine.

1. Install Homebrew

Homebrew is a package manager for macOS. It makes installing and updating applications and tools much easier.

To install Homebrew:

1. Open the Terminal app

2. Paste the following into your terminal and press Return:

   /bin/bash -c "$(curl -fsSL https://raw.githubusercontent.com/Homebrew/install/HEAD/install.sh)"

3. The Homebrew script will print out any instructions you need to follow.

Prerequisites and step-by-step instructions to install Homebrew

2. Install Git

Now that you have Homebrew installed, you can install Git on your machine.

1. Open the Terminal app

2. Enter the following and press Return:

   brew install git

3. Homebrew will print out any instructions you need to follow

Once you've installed Git, you need to configure your name and email address. These are shown in commit messages.

1. Set your name globally:

git config --global user.name "FIRST_NAME LAST_NAME"

2. Set your email address globally:

git config --global user.email "[email protected]"

3. Install Vale

To check your work against the style guide, you need to install Vale on your machine. Visual Studio Code uses this program to run checks when you save your work. To install Vale:

1. Open the Terminal app

2. Enter the following and press Return:

   brew install vale

3. Homebrew will print out any instructions you need to follow

4. Install Visual Studio Code

To install Visual Studio Code, head to their website and download the latest Universal build. Install this on your machine and

5. Set up an SSH key

SSH (Secure SHell) keys are used to authenticate with GitHub securely. If you don't already have an SSH key set up and present on your GitHub account, follow GitHub's guides to generate a new SSH key and add it to your GitHub account.

6. Clone the repository

Once you've set up your SSH key and added it to your GitHub account, you can clone the repository to your computer. To do this:

1. Open the Terminal app

2. Enter the following and press Return:

   git clone [email protected]:adjust/sdk-docs.git

3. Once the clone is complete, the repository is available in a folder called sdk-docs

Using Git

Git is a version control system that follows a tree-like model for managing parallel changes.

Branches

To ensure that contributors can make changes in parallel without overwriting one another's work, all changes should be submitted to new branches.

When you create a new branch locally, the branch only exists on your machine. You need to push the branch to create it on GitHub, then push your changes to make sure they're stored in the repository. If you're collaborating on a branch, changes need to be pushed so that other users can pull them and see the changes you've made.

An example workflow looks like this:

gitGraph
   commit
   commit
   branch ios-change
   checkout ios-change
   commit
   commit
   checkout main
   branch android-change
   checkout android-change
   commit
   checkout ios-change
   commit
   checkout android-change
   commit
   checkout main
   merge ios-change
   merge android-change
   commit

Loading

In this flow, a contributor creates a branch called ios-change to update some iOS documentation. At the same time, another contributor creates a branch called android-change to update some Android documentation. The two contributors work on their branches at different paces and submit pull requests to get their changes merged. When the changes are approved, both branches are merged into the main branch. The main branch now contains all of the changes made in both the ios-change and android-change branches.

Stages

Changes to files are made in stages. Unlike most other document systems where saving the file is enough to commit a change, Git uses the following workflow:

1. A changed file is staged using git add <filename>. This adds it to the staging area, which is the list of changes that will eventually make a commit. You can stage files when you have finished making changes to it, and leave files you're still working on. You can remove files from the staging area using git restore --staged <filename>. This keeps the changes you've made, but removes them from the staging area until you're ready.
2. A group of changes are committed to the current branch. This adds the changes to the local version of the branch so that they are recorded in the branch's history.
3. The local branch is pushed to the remote version of the branch to update it.

flowchart
   edit([The contributor changes a file\nand saves the change]) --> stage(The contributor stages the change)
   stage --> commit(The contributor makes a commit\ncontaining all staged changes)
   commit --> push([The contributor pushes all of their\ncommits to the remote branch])

Loading

This style of working ensures that contributors can work on a set of changes in isolation without needing to worry about changes being overwritten. Here's how to use Visual Studio Code to submit changes to the repository.

Editing the docs

Visual Studio Code is a one-stop shop for managing your editing, Git workflow, and Docker preview. Follow these instructions to start hacking on the docs.

1. Open the repo in VS Code

1. Open Visual Studio Code
2. Select File -> Open folder
3. Find the sdk-docs folder you cloned earlier and open it

You should see the repository structure in the sidebar.

2. Install extensions

To get the best experience, install the recommended extensions found in the root of the repository.

1. Select the Extensions icon in the sidebar or press Shift + Cmd + K

   

2. Enter @recommended in the search bar at the top to show the recommended extensions

   

3. Select the cloud icon next to the Workspace recommendations to install all recommended extensions

   

3. Start the Docker preview

To start a live preview that updates as you save your changes, follow these steps.

1. Open Docker Desktop

2. Go to Visual Studio Code and select Terminal -> New Terminal or press Ctrl + Shift + `

3. Enter the following into the terminal that appears at the bottom of the screen and press Return after each line:

   $ make build
   $ make preview

4. Open http://localhost:8000 to see your the live preview

When you are finished with the live preview, select the terminal and press Ctrl + C to stop the container.

4. Create a new branch

As mentioned above, all work should take place on a new branch. You can manage your branches easily in VS Code.

1. Select the branch indicator in the bottom-left of the screen to open the branch menu. By default, this shows the main branch name

   

2. In the branch menu, select + Create new branch...

   

3. Give your branch a name relating to what you're working on. Use lowercase letters and separate words with a hyphen (-). Press enter to save your branch

4. The branch indicator updates to show you're now working on the new branch

5. Edit the docs

Now it's time to edit the documentation! The documentation in this repository is written in a special flavor of Markdown called MyST. Check out the Markdown primer in this wiki for information about the syntax and conventions to use.

6. Use the source control menu to manage changes

As you save your changes, you'll notice the source control icon on the sidebar indicates the number of files you've changed.

Select this icon to open the source control menu.

Staging changes

When you're ready to stage a file, select the + icon next to it. It will move to the staging area above the other files.

If you make further changes to the file, it will stay in the staging area but a new entry will appear in the Changes section. Select the + button again to add those changes on top of the staged changes.

You can stage as many changes as you want to. To remove a staged change, select the - button next to the entry in the Staged Changes section.

Note: This doesn't undo your saved changes. To revert your changes, select the Discard changes icon on the file in question

Make a commit

Once you've staged all your changes, you need to make a commit. Each commit must include a short message summarizing the changes made. To write your commit message, enter it into the Message bar at the top of the source control menu.

When you've added your message, select the Commit button. All files in the Staged Changes section are committed to the branch and disappear from the source control menu.

Push changes

When you've committed all your changes, you need to push your changes.

1. Select the three dot menu in the source control menu to see more options

   

2. Select Push

3. If your branch is already published, your changes will be pushed. If the branch isn't already published, VS Code will ask you if you want to publish the branch. Select OK to publish the branch

   

Your changes are now published on the remote branch on GitHub. This allows other people to pull the branch.

7. Open a pull request

A pull request is a GitHub feature that enables you to submit changes for review. Other contributors can check your changes, submit suggestions, and help to catch any errors.

Follow GitHub's guide to Creating a pull request to open a pull request with your newly pushed branch.

In VS Code

If you've installed the GitHub Pull Requests and Issues extension and prefer to create the pull request directly from VS Code, select the Create Pull Request button in the source control menu.

Make sure your feature branch is selected in the Merge changes from section, and your target branch is selected in the Into section. Add a title and description and select Create to open the pull request.

VS Code will publish your branch and open the pull request summary in your editor.