contributing

development environment

getting started

all you need to do is clone Octagon and then run yarn install to get the component library and any dependencies
- git clone https://github.com/Tripwire/octagon.git
note: if you are running into lock file trouble, you may need to delete yarn.lock and it will be regenerated by yarn upon running yarn install

watching code changes

octagon offers two mechanisms to support development:

yarn dev - watch the source code & rebuild the library onchange
- this mode is strongly recommended when developing octagon and linking it into a consuming project
  - to develop this library in real-time whilst using it in another project:
    - run yarn link in this project's source
    - run yarn link react-octagon in the consuming project's source
yarn start - launch the interactive styleguide. see more below.

launch styleguide

run yarn start
open the URL (probably localhost:6060) to play w/ components as you develop them

this will launch the styleguide. all of your changes to files are hot-reloaded. if you want to ship a production version your will need to test and build octagon.

building components

when building components, please follow our Architecture Decisions. each component should include an accompanying example in a markdown file.

documenting components

all components should be documented per [styleguidist standards](https://react-styleguidist.js.org/docs/documenting.html], based on JSDoc). this allows Styleguidist to display comments and documentation in the interactive styleguide.

components should have a desciption

using a JSDoc comment block, describe each component.

/**
 * Pagination Control: controls pagination of results, allowing the user to 
 * change result pages through simple buttons.
 */

export default class PaginationControl extends React.PureComponent {

components propTypes should have a description

PaginationControl.propTypes = {
  /**
   * Set Pagination to disabled. Default is false.
   */
  disabled: PropTypes.bool,
  /**
   * Called when the control is blurred.
   * @param {Number} page target page number
   */
  onPageChange: PropTypes.func.isRequired,
  /**
   * Called when the page changes.
   * @param {Number} page target page number
   */
  page: PropTypes.number,
  /**
   * Set Pagination to disabled.
   */
  totalPages: PropTypes.number
  /**
   * Set total number of pages.
   */
}

components example code blocks should include a language tag

the language tag will generally be 'jsx', 'js', or 'css'. surround the code block with a triple grave accents and the langauge abbreviation.

```jsx
initialState = { page: 1 };
<PaginationControl
  page={state.page}
  totalPages={10}
  onPageChange={obj => setState({ page: obj.page })}
/>
```

react-based functional stateless components

octagon components are considered view-layer components and should generally be functional stateless components (see ADR002).

How to handle state is decided by the app (e.g. dealing with page number errors or and actual page number)
Positioning of the component will be decided by the app (e.g. 4px padding on the right and left)

<div style={{padding: '4px 0'}}>
  <PaginationControl
    page={state.page}
    totalPages={20}
    onPageChange={obj => {
      if (obj.error) {
        console.error(obj.error)
      } else {
        setState({ page: obj.page})
      }
    }}
  />
</div>

native octagon component styles

native octagon components use cssnext and should follow BEM CSS Standards. the styles below show a block, element, and modifier.

.pagination {
  display: inline-block;
  height: 30px;
  color: #657d8e;
  margin: 0 4px;
  background-color: white;
}

.pagination__button {
  border: 1px solid #bdc3c7;
  color: #657d8e;
  background-color: white;
  cursor: pointer;
  display: inline-block;
  padding: 0px;
  font-size: 28px;
  max-height: 30px;
}

.pagination__page-number_total-pages-unknown {
  font-size: 20px;
  line-height: 15px;
  vertical-align: baseline;
}

SUIR octagon component styles

SUIR octagon components use LESS for styling. more information can be found on Semantic UI's themeing page. to theme SUIR components, navigate to your theme folder, src/semantic-ui-theme, and add your styles in the to the component's: .variables and .overides files. (e.g. button.variables & button.overrides)

build for production

build octagon yarn build
- this will create the lib bundle which will contain production build
- this can be ingested by applications to use Octagon components
build styleguide yarn styleguide:build
- this will create the Styleguide folder, Build Octagon Component Library and Build Styleguidist
- note: this build is what is currently used for testing
test octagon
- both automated and manual tests (see testing info)
make sure your component meets the acceptance criteria

code of conduct

the code of conduct (coc) explains the bare minimum behavior expectations this project requires of its contributors. we adhere to the nodejs coc. please read it before participating.

issue contributions

when opening new issues or commenting on existing issues on this repository please make sure discussions are related to concrete technical issues with our package.

code contributions

this document will guide you through the contribution process.

step 1: fork

fork the project on github and check out your copy locally.

$ git clone git@github.com:username/octagon.git
$ cd octagon
$ git remote add upstream git://github.com/tripwire/octagon.git

which branch?

for developing new features and bug fixes, the master branch should be pulled and built upon.

step 2: branch

create a branch and start hacking:

$ git checkout -b my-branch -t origin/master

step 3: commit

we follow the default settings for semantic-release. please see the default commit message format for participation instructions.

commits should be small, targeted, and focused. unfocused changes need to be split into multiple prs and are subject to friendly but stubborn rejection.

step 4: test

Ensure that you have Docker installed for your OS.

run yarn lint and yarn format (IDE settings will help)
run yarn styleguide:build to build the style guide.
run yarn test to use our tests against your changes including webjerk image diffing
tests will likely initially fail if you have created or updated a component. this is because we are using Snapjerk image-diffing software.

if you approve of the changes Snapjerk displays you need will to update the reference set:

new images: set WEBJERK_ALLOW_NEW_IMAGES=1 in your env

new changed images: set WEBJERK_APPROVE_CHANGES=1 in your env

removed images: simply remove the images from your reference set

manually test against modern browsers (Chrome evergreen, FF evergreen, & Edge)

step 5: push

$ git push origin my-branch

go to https://github.com/yourusername/octagon and select your branch. click the 'pull request' button and fill out the form.

pull requests are usually reviewed within a few days.

step 6: discuss and update

you will probably get feedback or requests for changes to your pull request. this is a big part of the submission process, so don't be disheartened!

to make changes to an existing pull request, make the changes to your branch. when you push that branch to your fork, github will automatically update the pull request.

you can push more commits to your branch:

$ git add my/changed/files
$ git commit
$ git push origin my-branch

or you can rebase against master:

$ git fetch --all
$ git rebase origin/master
$ git push --force-with-lease origin my-branch

or you can amend the last commit (for example if you want to change the commit log).

$ git add any/changed/files
$ git commit --amend
$ git push --force-with-lease origin my-branch

important: the git push --force-with-lease command is one of the few ways to delete history in git. before you use it, make sure you understand the risks. if in doubt, you can always ask for guidance in the pull request or on irc in the #node-dev channel.

feel free to post a comment in the pull request to ping reviewers if you are awaiting an answer on something. if you encounter words or acronyms that seem unfamiliar, check out this glossary.

note that multiple commits often get squashed when they are landed (see the notes about commit squashing).

step 7: landing

in order to get landed, a pull request needs to be reviewed and approved by at least one tripwire collaborator and pass a ci (continuous integration) test run. after that, as long as there are no objections from a collaborator, the pull request can be merged.

when a collaborator lands your pull request, they will post a comment to the pull request page mentioning the commit(s) it landed as. github often shows the pull request as closed at this point, but don't worry. if you look at the branch you raised your pull request against (probably master), you should see a commit with your name on it. congratulations and thanks for your contribution!

pull request approvals

a pull request is approved either by saying "+1" or a thumbs up emoji. if the author has merge access, he/she may merge after getting collaborator approval. otherwise, the collaborator should recognize the case where the change author does not have merge access, and should merge on behalf of the author.

github's pull request review feature can be used during the process. for more information, check out the video tutorial or the official documentation.

after you push new changes to your branch, you need to get approval for these new changes again, even if github shows "approved" because the reviewers have hit the buttons before.

acceptance criteria

component has been reviewed by at least one technical project member
component has been reviewed by UX team member
component passes all tests (automated and manual)
component has sufficient examples to prove prove handling of various states
component includes data-hooks for QA testing

resources

BEM
CSS Next
React
Semantic UI Less
Semantic UI React
Semantic UI
Snapjerk
Styleguidist

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

CONTRIBUTING.md

CONTRIBUTING.md

contributing

development environment

getting started

watching code changes

launch styleguide

building components

documenting components

components should have a desciption

components propTypes should have a description

components example code blocks should include a language tag

react-based functional stateless components

native octagon component styles

SUIR octagon component styles

build for production

code of conduct

issue contributions

code contributions

step 1: fork

which branch?

step 2: branch

step 3: commit

step 4: test

step 5: push

step 6: discuss and update

step 7: landing

pull request approvals

acceptance criteria

resources

Files

CONTRIBUTING.md

Latest commit

History

CONTRIBUTING.md

File metadata and controls

contributing

development environment

getting started

watching code changes

launch styleguide

building components

documenting components

components should have a desciption

components propTypes should have a description

components example code blocks should include a language tag

react-based functional stateless components

native octagon component styles

SUIR octagon component styles

build for production

code of conduct

issue contributions

code contributions

step 1: fork

which branch?

step 2: branch

step 3: commit

step 4: test

step 5: push

step 6: discuss and update

step 7: landing

pull request approvals

acceptance criteria

resources