-
Notifications
You must be signed in to change notification settings - Fork 771
Editing Updating content on carbondesignsystem.com
- Step 1: Setup your machine
- Step 2: Get a local version of the GitHub repo on your computer
- Step 3: Install all the necessary dependencies and run the website locally
- Step 4: Creating and working from a branch
- Step 5: Updating content
- Step 6: Creating a Pull Request
- Step 7: Updating your repo and your branch
- Step 8: Making more changes
- Terminal cheatsheet
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 v10
nvm alias default v10
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.
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:
/bin/bash -c "$(curl -fsSL https://raw.githubusercontent.com/Homebrew/install/master/install.sh)"
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
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.
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.
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
.
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.
- Go to your personal GitHub account and find the repo you want to delete
- Go to Settings
- Scroll all the way down, and click Delete this repository
- This will prompt you to type in the name of the repository, so do that and then click the confirm button
- You also have to delete the repo folder from your computer
- Go to the repo page
- Click Fork to fork the repo to your GitHub account.
This will bring you to your personal fork of the repo.
- 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.
- 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 commandls
.
Example:
- Once it's done cloning, you can move into the cloned repo by typing
cd carbon-website
- Make sure you're in the
carbon-website
folder in your terminal, and run the commandyarn
. This will install all the necessary dependencies that the website need to run properly. This might take a while.
- 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 commandyarn dev
. - Go to the URL
http://localhost:8000
in your browser to see the website. To stop the server in the terminal, you can pressCTRL + 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
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.
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.
- 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.
- Type in
git branch
again to make sure you're in the correct branch. - Type in
yarn dev
again to run the website locally from your branch. Navigate tolocalhost:8000
in your browser to see it live.
- Open up your code editor, and open up the
carbon-website
folder in your editor. - 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. - Once you're happy with the changes you have done, go back to your terminal and press
CTRL + C
to stop the server.
- In your terminal, make sure you're in the correct branch by typing
git branch
. - To see a list of the changes you've made, type in
git status
. - You then need to add your changes. Do this by typing in the following:
git add .
-
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
.
- Make sure your commit message is descriptive and preferably follows the
git commit -m "Your commit message here"
- You're now ready to push up your changes! You can do this by typing the following:
git push origin your-branch-name
- Go to the Design system website repo, and you should see your branch pop up on the front page.
- Click on Compare & pull request
- Fill out the title of your pull request, and write a description of the changes you've done, and then click Create pull request.
- 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.
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:
- Navigate to the repo folder by using the
cd
command - 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.
- Once you're in the master branch, type in the following:
git pull upstream master
- Your local repo is now up to date.
- Switch back to your branch
git checkout -b your-branch-name
, and rungit 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.
- After doing
git rebase master
and a merge conflict message shows up, type ingit status
to see a list of the files that are affected. - 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!
- 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.
- Once all the conflicts are resolved, then run the command
git push -f origin your-branch-name
to update your pull request.
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.
- In your terminal, if you're in a different branch than master, type in
git checkout master
. - Update your local repo by typing in
git pull upstream master
. - Your
master
branch is now updated, and you can create a new branch by typing ingit checkout -b your-new-branch-name
. - You're now good to go!
git checkout master
git pull upstream master
git checkout master
git pull upstream master
git checkout -b your-new-branch
git checkout master
git pull upstream master
git checkout your-branch
git rebase master
git checkout your-branch
git status
git add .
git commit -m "your commit message"
git push origin your-branch
git checkout your-branch
git rebase master
// fix conflicts in the files affected
git add .
git rebase --continue
git push -f origin your-branch