Updating content on carbondesignsystem.com

Table of contents

• Step 1: Setup your machine
  • Install Homebrew
  • Install Yarn
  • [Optional] Install VS Code
• Step 2: Get a local version of the GitHub repo on your computer
  • Deleting a repo
  • Forking and cloning a repo
• Step 3: Install all the necessary dependencies and run the website locally
• Step 4: Creating and working from a branch
  • Check which branch you're currently in
  • Create a new branch
• Step 5: Updating content
• Step 6: Creating a Pull Request
• Step 7: Updating your repo and your branch
  • Dealing with merge conflicts
• Step 8: Making more changes
• Terminal cheatsheet

Step 1: Setup your machine

Before getting started, you will need to install some of the tools we use to build the website. These tools also can be used to contribute to some of our other projects, as well! To start off, you'll want to install a version of Node.js npm, and yarn. These are the powerhouse tools that drive most of the work we do in JavaScript.

While you can install Node.js directly from their website, we recommend using a tool called nvm. Node.js can change versions multiple times in a year, and this tool helps to easily update to the latest version.

To install nvm, you can follow their install instructions. If this is your first time working in the terminal, all you will need to do is open up your terminal of choice (either Terminal.app or iTerm) and run the following command next to the prompt:

curl -o- https://raw.githubusercontent.com/creationix/nvm/v0.33.11/install.sh | bash

This command will install nvm for you, allowing you to run nvm commands directly from your terminal. When this command completes, you should see a message that looks like the following:

=> Close and reopen your terminal to start using nvm or run the following to use it now:

export NVM_DIR="$HOME/.nvm"
[ -s "$NVM_DIR/nvm.sh" ] && \. "$NVM_DIR/nvm.sh"  # This loads nvm

After you see this, you will need to run:

echo 'export NVM_DIR="$HOME/.nvm"
[ -s "$NVM_DIR/nvm.sh" ] && \. "$NVM_DIR/nvm.sh"  # This loads nvm' > ~/.bash_profile

When this is complete, you should open a new tab in your terminal and close the one that you were using to enter in the commands above.

Tip: to open a new tab, you can use CMD+T

In this new tab, you should be able to run the following command from nvm:

nvm install v8
nvm alias default v8

This will install Node.js v8.x and alias is as your default Node.js version.

Now, each time you open the terminal you should be able to run the command node -v and see an output that v8.x.y. In addition to installing Node.js and the node command, this work will also install the npm tool for you to use in the terminal.

To find out how to install Yarn, head to this section.

Install Homebrew

Homebrew is a tool used for installing software on MacOS machines. Installing this on your machine is completely optional, but it can make it easier to install other tools that might be relevant while working on our projects. To install Homebrew, you can run the following command in your terminal:

/usr/bin/ruby -e "$(curl -fsSL https://raw.githubusercontent.com/Homebrew/install/master/install)"

Install Yarn

Yarn is an alternative to the npm we use for the website. You can install Yarn by using Homebrew, or by following their install instructions here.

If you're using homebrew, you can install Yarn by running:

brew install yarn --without-node

[Optional] Install VS Code

VS Code is a popular code editor that a good number of folks on our team like to use. This editor has a number of advantages, including:

• Being able to view an entire project structure at once through its file explorer
• An integrated terminal so you don't have to worry about running a separate terminal application
• Easy way to edit project files and view changes through a markdown preview function
• A number of plugins that can simplify your GitHub workflow

To install VS Code, you can visit their website which should have a button to download the editor for your specific computer. After the download completes, you should unzip the file and drag the Visual Studio Code.app into your Applications folder.

Once you've moved Visual Studio Code.app over, you should run it and accept any security prompts that may pop-up. After launching VS Code, you should see a screen similar to:

You can use this window to open up a specific folder on your computer that contains your project's files. For the carbon-website project, selecting the folder would look like:

Clicking Open on the folder should populate an EXPLORER section on the left-hand side of VS Code. Using this, you can navigate to any file in the project, make edits to it, and more.

Editing Markdown

If you're working with markdown, it might be helpful to use the Markdown Preview functionality built into VS Code. When you have a markdown file open in your editor, you can go to View -> Command Palette (or Shift+CMD+P) and it will bring up a prompt at the top of the file similar to the following:

Inside of this command palette, you can type: Markdown to view all the commands associated with VS Code's markdown plugin. To preview your changes, you can use select Markdown: Open Preview to the Site and hit Enter. This should open up a panel where you can view a rendered version of your markdown file alongside the text for the file. If you make changes to the file on the left, it should update on the right. Similarly, if you scroll in the markdown file it will mirror the location on the left hand side.

Working with GitHub

VS Code has an excellent integration with GitHub, specifically for Pull Requests. You can view the full details for this behavior over in this blog post.

You can install this plugin by visiting the plugin URL and clicking Install. You should see a prompt saying Open Visual Studio Code.app? where you can then click Open Visual Studio Code.app. You should see a screen that looks like the following:

On this screen, you need to click Install for the plugin to install in VS Code, and then click Reload when it completes. Reload should appear in the same location where the Install button was.

After reloading, you should see a dialog box in the lower right hand side of the screen requesting for you to sign in with your public GitHub.com login:

You should click Sign In and accept the following dialog requests in the browser. After you have signed in, you should click on the icon that says Source Control (it should be the third icon from the top of the left sidebar). This will open up a panel that looks like the following:

Using the GITHUB PULL REQUESTS section, you can view all the Pull Requests on the project that you are working on. When you click on a specific Pull Request, you should be able to view all the changes associated with that Pull Request. You can also view the Pull Request directly by clicking on Description.

If you would like to view the changes on your computer, you can click the Checkout button for it to checkout the specific Pull Request that you are viewing. Clicking this button will allow you to view all the changed files on your machine by going back to the explorer tab (first icon from the top). When you're done looking at the changes, you can re-visit the Pull Request you checked out and click Exit Review Mode.

Step 2: Get a local version of the GitHub repo on your computer

If you already have the repo forked, but you suspect that it is very out of date, then the easiest solution is to delete it both on your computer and from your GitHub profile and then re-fork it.

Deleting a repo

1. Go to your personal GitHub account and find the repo you want to delete
2. Go to Settings
3. Scroll all the way down, and click Delete this repository

4. This will prompt you to type in the name of the repository, so do that and then click the confirm button
5. You also have to delete the repo folder from your computer

Forking and cloning a repo

1. Go to the repo page
2. Click Fork to fork the repo to your GitHub account.

This will bring you to your personal fork of the repo.

3. Next you need to clone your personal fork to your computer. Click on Clone or download, and copy the link that shows up in the text field.

4. Open up your terminal, and use the command cd to move to the folder where you want to clone your repo. To see where you are at any point, you can use the command ls.

Example:

5. Once it's done cloning, you can move into the cloned repo by typing cd carbon-website

Step 3: Install all the necessary dependencies and run the website locally

1. Make sure you're in the carbon-website folder in your terminal, and run the command yarn. This will install all the necessary dependencies that the website need to run properly. This might take a while.

• Build the website addons package. cd packages/addons-website and yarn build
• If that was successful, you should be able to run the website locally now by going back to the root folder cd ../../ and running the command yarn dev.
• Go to the URL http://localhost:8000 in your browser to see the website. To stop the server in the terminal, you can press CTRL + C.
• You will also need to set the remote URL for your local repo, so GitHub knows that you want to connect to the original website repo. In your terminal type the following:

git remote add upstream [email protected]:carbon-design-system/carbon-website.git

Step 4: Creating and working from a branch

Before you make a change or content update, you need to make sure that you're working in a branch. By default after cloning a repo you're going to be in the master branch.

Check which branch you're currently in

To check which branch you are in at any point, you type git branch in the terminal. This will show a list of all your branches with an * next to the branch you're currently in.

Create a new branch

1. To create a new branch, type in the following command:

git checkout -b your-branch-name

Keep the branch names short and sweet, and with no spaces.

2. Type in git branch again to make sure you're in the correct branch.
3. Type in yarn dev again to run the website locally from your branch. Navigate to localhost:8000 in your browser to see it live.

Step 5: Updating content

1. Open up your code editor, and open up the carbon-website folder in your editor.
2. All the content for the website is inside src/content. Navigate to the file you want to update and make some changes. Once you save the file, you will see the content being updated automatically in your browser.
3. Once you're happy with the changes you have done, go back to your terminal and press CTRL + C to stop the server.

Step 6: Creating a Pull Request

1. In your terminal, make sure you're in the correct branch by typing git branch.
2. To see a list of the changes you've made, type in git status.
3. You then need to add your changes. Do this by typing in the following:

git add .

4. After adding, you need to commit your changes and add a commit message explaining what changes you've done.

   • Make sure your commit message is descriptive and preferably follows the <type>(<scope>): <subject> format. For example, fix (typography-productive): typo in chart.

git commit -m "Your commit message here"

5. You're now ready to push up your changes! You can do this by typing the following:

git push origin your-branch-name

6. Go to the Design system website repo, and you should see your branch pop up on the front page.

7. Click on Compare & pull request
8. Fill out the title of your pull request, and write a description of the changes you've done, and then click Create pull request.
9. Your PR is now ready to be reviewed! Once it's reviewed and someone presses Squash and merge the contents of your branch will be merged into the master branch.

Step 7: Updating your repo and your branch

Before making any changes, you should always make sure that your local repo is up to date with the original repo. To do this, do following in the terminal:

1. Navigate to the repo folder by using the cd command
2. Once in the repo folder, change to the master branch by typing in

git checkout master

Note that you can only do this when you don't have any uncommitted changes in your branch. If this is the case you will something like this in the terminal:

Switch back to your branch, and add and commit the changes you made.

3. Once you're in the master branch, type in the following:

git pull upstream master

4. Your local repo is now up to date.
5. Switch back to your branch git checkout -b your-branch-name, and run git rebase master to update the branch. If there are no merge conflicts then you can keep working in the branch. If however, there are merge conflicts, follow the next steps.

Dealing with merge conflicts

1. After doing git rebase master and a merge conflict message shows up, type in git status to see a list of the files that are affected.
2. Go to your code editor and fix the files with the merge conflicts.

The conflict will show up like this in the file:

<<<<<<< HEAD
Users may have multiple accordions open at the same time. The entire header area is clickable to expand or collapse the content below.
=======
Users may have multiple accordions open at the same time. The entire header area is clickable to expand or collapse the content below. Yo yo!
>>>>>>> your latest commit message here

Everything inside HEAD is the original content from the master branch, and everything inside the ======= and >>>>>>> your latest commit message here is the changes you made. Choose which one you want to keep (usually the changes you did), and remove everything inside HEAD, and also the ======== and >>>>>>> your latest commit message here. You'll end up with only the changes you want to keep in the file.

Users may have multiple accordions open at the same time. The entire header area is clickable to expand or collapse the content below. Yo yo!

3. Once you've fixed all the files affected by the merge conflict, go back to the terminal, and type in:

git add .

Do not commit these changes.

Then move on with the rebasing by typing in git rebase --continue. If there are no more conflicts, the terminal will bring you back to your branch. If there are more conflicts then type in git status again to see which files are affected, and re-do step 2 and 3.

4. Once all the conflicts are resolved, then run the command git push -f origin your-branch-name to update your pull request.

Step 8: Making more changes

Make sure that you have a separate branch for each pull request you want to make. This means that once a PR is merged, you'll need to create a new branch if you want to update more content.

1. In your terminal, if you're in a different branch than master, type in git checkout master.
2. Update your local repo by typing in git pull upstream master.
3. Your master branch is now updated, and you can create a new branch by typing in git checkout -b your-new-branch-name.
4. You're now good to go!

Terminal Cheatsheet

Updating your local repo

git checkout master
git pull upstream master

Creating a new branch

git checkout master
git pull upstream master
git checkout -b your-new-branch

Updating your branch

git checkout master
git pull upstream master
git checkout your-branch
git rebase master

Creating a pull request

git checkout your-branch
git status
git add .
git commit -m "your commit message"
git push origin your-branch

Resolve a merge conflict

git checkout your-branch
git rebase master
// fix conflicts in the files affected
git add .
git rebase --continue
git push -f origin your-branch