@sproutsocial/racine

Racine

“A single word often betrays a great design.”

— Jean Racine

Racine is a React component library consisting of documented, reusable components built for consumption in Sprout Social’s web products. The design principals of this library are based off Sprout Social’s Design System, Seeds.

Components are implemented using React and styled-components. Racine components encapsulate logic, styles, example usage and documentation into generic components representing common interface elements.

See this page to learn more about how Racine components are built.

Racine Setup

To get started running Racine locally, make sure you have Node.js, npm and Yarn installed and then clone or download this GitHub repo, navigate in terminal to the project's folder and run the following commands:

$ yarn install
$ yarn start

Contributing to Racine

Contributions to Racine are welcome from any part of the team, whether updating component presets, documentation or adding a new component to the library. If you are interested in getting involved, feel free to submit a Pull Request, create a ticket on the Design Systems Jira Board, or join us at the Component Library Guild meeting.

Contents

• New Components
• Working with Code
  • Committing Changes
  • Submitting PRs to Racine
  • Releasing
  • Consuming a Racine Component

Working with Code

Committing Changes

We use standard-version to automatically update the changelog and decide new version numbers. As such, we need commit messages to follow a consistent format (drawn from conventional commits).

Example commit messages (simply match this pattern and your commit message will be accepted):

• git commit -m "feat: add Alert component"
• git commit -m "fix(Alert): display the correct icon when type is \"danger\"" -m "fixes RD-999"
• git commit -m "feat(Alert): remove \"danger\" Alert type" -m "BREAKING CHANGE: removes one option for \"type\" prop"
• git commit -m "feat(icons): add reporting range icon"
• git commit -m "docs: update accessibility statuses"
• git commit -m "feat(dependencies): upgrade classnames to 2.2.5"
• git commit -m "chore(dependencies): upgrade babel dependencies to latest version" (chore because they are devDependencies)
• git commit -m "feat(build): add dist/iconList.js to package output"

Commit message format:

type(scope?): subject

body?

footer?

type is one of the following:

• fix: Solves a bug
• feat: Adds a new feature
• build: Affects the build system or external dependencies
• docs: Adds or alters documentation or the Racine app
• perf: Improves performance
• test: Adds or modifies tests
• chore: Other changes that don't modify src or test files

scope is optional but, with few exceptions, should be used for all feat and fix commits. Common scopes include:

• [ComponentName]: Changes to a Racine component
• icons: Changes to the SVG icon files
• dependencies: Changes to dependencies should be feat, and devDependencies should be chore
• build: Changes to the build that make significant changes to the published package, should be a feat or fix

Feel free to suggest additional scope options

subject requirements:

• starts with lower case
• uses the imperative, present tense: "change" not "changed" nor "changes"
• includes motivation for the change and contrasts with previous behavior

body is optional and allows for more details to be added

footer contains meta-information about pull requests, e.g. "fixes RD-999", referring to a Jira ticket

Submitting PRs to Racine

Before submitting a PR to Racine, please review the Racine Git Worflow Chart for an overview of the process.

1. Create a new branch

$ git checkout -b my-branch-name

1. Make your changes

2. Test your changes

$ yarn test

1. Commit your changes, following the commit message guidelines above

$ git add -A
$ git commit -m "MESSAGE"

1. Push your change

$ git push origin my-branch-name

1. Open a PR (you should see the option to open a PR at the top of the Racine Github page)

2. Once your PR is tested, approved and passes the automated validation tasks, you can "Squash and Merge" it (this will be the only merge option available). Please double check that the squashed commit message still follows our commit guidelines.

Congrats, thanks for contributing!

Releasing

Only those with admin privileges to the Racine repo can publish new versions of the package. Contact one of the following about releasing a new version:

• Ben Lister
• Ben Rothman
• Chase McCoy
• Doug Garofalo
• Kevin Bertram
• Chris Ege
• Westin Wrzesinski

$ git checkout master
$ git pull origin master --tags
$ yarn release

Make sure everything looks good. If you need to make changes, be sure to undo the release commit and delete the new tag. Once everything looks goood, run

$ git push --follow-tags

Finally, go to Jenkins and trigger final publishing on the newly-created tag.

Admins: The release script uses standard-version to automatically pick a new package version and update the CHANGELOG based on the commits since the last release. You will be able to confirm the next version of the package before pushing your changes to GitHub. Note that the package will not automatically be published to NPM. You will have to manually go to Jenkins and click to complete the release (see image below).

Consuming a Racine Component

Consuming a Racine component can be done in a number of ways, depending on it's stage of development.

Testing local Racine changes in another project

Test any local package in another project by utilizing yarn link. Below is an example workflow to link Racine to web-app-core.

• Navigate to your local copy of Racine in a terminal window

  $ cd ~/YourCodeFolder/racine
  $ yarn link # only needs to be run once
  $ yarn start
  

  Note: This build task packages all Racine components into the bundle, not just the specific components you are adding or modifying. After yarn link succeeds and Racine is globally linked, you shouldn't have to run link again.

• Navigate to the folder you wish to use Racine components in your terminal (such as web-app-core) and complete the link

  $ cd ~/YourCodeFolder/web-app-core
  $ yarn link "@sproutsocial/racine"
  $ yarn start
  

• You can now use any components from your local instance of Racine in your project. See below for an example usage

  /* ~/YourCodeFolder/web-app-core/YourFile.js */
  import {Icon} from '@sproutsocial/racine';
  // ...
  <Icon name='compose' />
  

• When you are done, be sure to unlink Racine so you are using the app's version of the package

  $ yarn unlink "@sproutsocial/racine"
  

A Video walkthrough of this process can be found here.

Consuming a published Racine component in your project

To consume a Racine component that has been merged and published, do the following:

• Check your project's package.json to make sure you are importing the latest version of Racine. If you need to update the Racine version. If an update is needed, you can either run yarn upgrade @sproutsocial/racine or manually update the version number in your project’s package.json.

• Import and use the component as desired

  import {Icon} from '@sproutsocial/racine';
  // ...
  <Icon name='compose' />