Setting up your environment - one time only!

If this is your first time creating a pull request (PR) and setting up your local enviornment, follow these steps below. You will only have to do these steps once to get started with making PRs.

Downloading the tools

1. Create a personal GitHub account.
2. You can use your personal or work email to associate. It is not a security risk to use your personal email when creating a public GitHub account.
3. Use the GitHub Mapper Tool to map your personal GitHub account to your Enterprise GitHub account.
4. Download and install the VSCode code editor.

• Optional: Install a theme. It’ll be easier on your eyes.

5. Install XCode Command Line Developer Tools

• Search for XCode in the Apple App Store and install it.
• Xcode comes with git, so you should have no need to install git separately.

6. Install Node from NVM Package Manager, found at this link

• To install Node, you'll need to have XCode open and have agreed to their terms to proceed with the installation.
• Open Terminal in your applications on Mac.
• For MacOS, type the command: curl -o- https://raw.githubusercontent.com/nvm-sh/nvm/v0.39.7/install.sh | bash
• Then enter this command: nvm install 20

VSCode setup

7. Install Yarn:

• With VSCode open, click the View menu, and then select Terminal. This is where you can enter commands. You can also open a terminal by clicking CTRL+`.
• From your terminal, enter the following command: curl -o- -L https://yarnpkg.com/install.sh | bash

8. To read MDX files more easily, install and configure MDX language support.

9. Install and configure Prettier.

• Once you've installed Prettier you'll then need to add some additional lines of code to the VSCode settings. In the OS navigation bar for VSCode, select Code > Settings > Settings. At the top right of the settings panel, there is a file icon that reads "Open settings (JSON)" when hovered. In the settings file, add these two lines of code:

`"editor.formatOnSave": true,`

`"editor.defaultFormatter": "esbenp.prettier-vscode",`

• This change will format the MDX file you’re working on in a way that follows Carbon’s coding practices every time you save the file.

10. Optional: Set up your terminal and install Oh My Zsh!. This helps make your terminal themeable, making things easier to read, and will show the branch you’re on when you’re making changes. It even has an auto-complete when you’re typing in the terminal.

• To install, open the Terminal app on Mac and type in sh -c "$(curl -fsSL https://raw.githubusercontent.com/ohmyzsh/ohmyzsh/master/tools/install.sh)". Hit Enter to install Oh My Zsh!

11. Optional: Configure SSH Key & Fork and clone the repo.

• The alternative to SSH is to configure using HTTPS.
• If you already have an SSH key configured for your team on GitHub Enterprise, you can follow this guide to have multiple keys configured.
• If you don’t have an SSH key configured for your team, follow the video to set up your SSH key:
• https://www.youtube.com/watch?v=X40b9x9BFGo Towards the end of the video, they show forking and cloning a repo.
• Repo to fork and clone - https://github.com/carbon-design-system/carbon-website
• After it finishes cloning, type cd carbon-website to change your directory to the Carbon website repo directory so you can begin working with the CDS guidelines.
• Create and configure your upstream remote: https://docs.github.com/en/get-started/getting-started-with-git/managing-remote-repositories
• git remote add upstream [email protected]:carbon-design-system/carbon-website.git

Making changes to the Carbon Design System website

You can accomplish this part purely through VS Code or use the GitHub Desktop app to help manage the process visually.

VS Code

1. Open an issue. Here’s an example issue.
2. Open a terminal in VS Code with CTRL+` or use the browser navigation at the top: Terminal > New Terminal.
3. Select File > Open Folder, and select the carbon-website folder.
4. With the NVM Package Manager installed, type nvm use to begin using the correct version of Node, the stack that powers the Carbon website.
5. To get the latest changes to the Carbon site type git pull upstream main. Another way to do this is to go to your forked version of the website in GitHub in the browser and sync your fork to have all the current updates.
6. To download the correct dependencies, type yarn.
7. Make a new branch (this is where your new content will live) by typing git checkout -b yourbranchname. We suggest you name your branch after your GitHub issue.
8. To start the development environment and begin making your changes, type yarn dev.
9. Make changes to src\pages\whateverpage.
10. When you’re done making changes, go to your terminal and click CTRL+C to stop the development environment.
11. Check your changes on http://localhost:8000/.
12. When you’re happy with the changes, push your content by following the instructions in the video under “Making your branch and pushing content”.

GitHub Desktop app

1. Download GitHub Desktop from the App store.
2. Open the GitHub Desktop app.
3. At the top of the application page will be dropdowns for "Current Repository" and "Current branch".
4. Make sure Current repository is set to carbon-website.
5. Open the Current Branch dropdown and select main to switch to the latest version of the website.
6. In Current Branch, click "New Branch". A modal will appear to Create a Branch.
7. Name your branch – usually a descriptive title that includes the pages you are updating.
8. Under "Create branch based on..." make sure main is selected. Click "Create Branch".

Making your branch and pushing content

GitHub Desktop app

1. Select “Main” as current branch at top of page.
2. At Pull Origin, click “Fetch origin” to get most current version of your file.

VS Code

1. Use the left nav to click into the webpage that you are going to be updating.
2. In the terminal, check that it is using the correct node by typing node -v. You should be seeing v20.
3. Type yarn and then yarn dev in the terminal to check that yarn is working correctly. It is building a local file of the Carbon site.

In Browser

1. Copy the local host url http://localhost:8000/ into browser.
2. Navigate to webpage you will be updating.

VS Code

1. Click “Main” in bottom left footer. Click “Create a new branch” and create name (without using spaces).
2. Add whatever changes you will be making to the webpage and click Command S to save.
3. To change images, drag image to image folder in left nav (need to make sure it’s under the correct page folder) and name it to match the naming structure of the other images in the folder. Then replace the image name in the page code with the new name.

In Browser

1. Navigate to the local host url again, refresh the page, and check changes are made.

VS Code

1. Source Control in left nav which will have listed all changed files. Press “+” to stage changes. Add a message to explain the update (something like ”Update and Page Name”) and press Commit.

GitHub Desktop app

1. Click on "Publish Branch" CTA.

In Browser

1. Go to https://github.com/carbon-design-system/carbon-for-products-website and click “compare and pull request” and then write description of the assignment. Assign yourself and add reviewer if necessary. Click dropdown next to primary page CTA and change to “Draft pull request”. - Note: Never click “Publish pull request”. Then click the “Draft pull request” CTA and wait for all checks to complete

Alternate to GitHub Desktop app Step is VS Code Terminal

1. Type git add. and hit the Enter key. Then type git commit -m “name of change” and hit Enter.
2. Then type git push origin [name of your file] and then it will prompt you to sign into GitHub.
3. Click “Compare and Pull Request” CTA.
4. Then follow the same steps as in the GitHub Desktop path

• Note: VSCode notes: Control + C will get you out of the local build Command + S to save

Easy way

• https://ibm.box.com/shared/static/r3cgm3ncsb16yy6wfg63wzvoj78bn4pr.mp4
• https://ibm.webex.com/ibm/ldr.php?RCID=42474a313a5d26e4608eb9262d074d0e
• pw: nJaUdN72

Harder way

1. Pull the main branch from the upstream remote:

• In a terminal, type git pull upstream main

2. Make a new branch (this is where your new content will live) by typing git checkout -b
3. Commit the code and push your changes by typing git add
4. Type git commit -m “docs(<areayouareworkingin>): <short description of changes made>”
5. Type git push origin yourbranchname
6. Create pull request:

• Follow the link of the newly created branch on GitHub
• Click Create pull request
• Complete the form and submit the pull request

Getting your PR approved is up to the Carbon Design System org. After they approve it, they’ll merge the changes into the main branch.

When you’re finished working on that branch type git checkout main to get back to the main branch and start the process all over again!

Note that the Carbon websites make use of the Carbon Gatsby theme and it's components. More information can be found on the Carbon Gatsby theme website.