PayEx DesignGuide
Installing / Getting started
The installation guides in this file is for further development of the DesignGuide, and is not necessary if you plan to use the DesignGuide in your project.
Prerequisites
DesignGuide requires Node.js (includes npm).
Installing
- Open a terminal and navigate to repo root
npm install
npm start
- Go to http://localhost:3000
- Works? If not, contact us on Slack (#design-guide-general).
- Get to work.
Set up Git Hooks
- Open a terminal and navigate to repo root
- Run
git config core.hooksPath .githooks
Developing
Built with
Setting up Dev
- Running the command
npm start
starts the webpack dev server, (which is configured in~/webpack.config.js
). If any changes is made to this file, or any files directly influencing this file (i.e. any loaders or plugins) you need to restart the server. - The script
npm start
will start the dev server in development mode. If you wish to run the dev server in production-like environment run the commandnpm run start:prod
.
Importing components
When importing different components in the files you create, you can use shortcuts for common paths. The shortcuts are as following:
~
- root of the project (exampleimport package from "~/package";
).$
-~/src
-folder (exampleimport px from "$/px-script";
).@
-~/src/App/components
-folder (exampleimport Alert from "@/Alert";
).#
-~/src/App/Documentation/utils
-folder (exampleimport { DocToc } from "#";
).
The shortcuts are specified in the ~/.babelrc
-file. Specifying the prefix-shortcuts in the ~/jsconfig.json
-file enables path intellisense for the shortcuts (at least in VSCode).
Building
To start building, run the command npm run build
to start in dev-mode, or npm run build:prod
for production-mode. This will make webpack start bundling everything and make static files in the ~/dist/
-folder. Also make sure all tests pass, or make changes to them accordingly.
Note: Running the command
npm run build:prod
will delete all files already located in~/dist
.
Versioning
DesignGuide uses semantic versioning. This means that internally, DesignGuide will use a major.minor.patch
version number to signal what the changes in each release surmount to. This also means both CSS and JavaScript files are versioned in lockstep, so whenever a new version of the CSS is released, a new version of the JavaScript will be as well.
Tests
- Open a terminal and navigate to repo root
- Run the command
npm test
- Many of the tests are snapshot based, and runs against already created snapshots. If you need to update the snapshots due to changes run the command
npm run test:update
. - A test coverage report is generated after running the tests. This can be found in
~/coverage
.
- Many of the tests are snapshot based, and runs against already created snapshots. If you need to update the snapshots due to changes run the command
Note: Snapshot testing is pretty unforgiving, so if you make ANY changes to how a component, which already has a snapshot, is rendered, the tests WILL crash! So make sure to run
npm run test:update
before committing.
Code style
Coding style rules set in ~/.eslintrc
& ~/.stylelintrc
.
Make sure to follow the syntax rules enforced by eslint & stylelint.
Contributing
- Bug reports: File bugs as Github issues.
- Feature suggestions: File as Github issue or discuss the feature on Slack (#design-guide-general).
- Code contribtions: Code contribtions are highly encouraged, but discuss the feature/bugfix in an issue or on Slack before you start coding.
Creating a release
Before merging to master to create a release make sure you follow these steps:
- Make sure the linting (
npm run lint
) and unit tests pass (npm test
). - Update the version in
~/package.json
- Make sure the changelog is correct (date and version) and only contains changes for the current release.
- Update the version in the url to the shield image at the top of this
README.md
. - Commit the changes and push to
develop
. - Change branch to
master
. - Merge
develop
intomaster
without fastforward (--no-ff
). - Create a tag with the new commit.
- Push the tagged commit to
master
.
AppVeyor will now create and deploy a release on both github and design.payex.com.
After pushing to master, complete the following steps:
- Change back to
develop
. - Remove the content of changelog (leave the heading).
- Commit the file and push it.
Maintainers
Contents of this project
~/coverage
- Test coverage report for the project (not commited to repo).~/dist
- Static files generated by webpack (not commited to repo).~/src
- All the source files.~/build
- Config files for AppVeyor, and other files required for the AppVeyor build process.~/tools
- Various tools, mostly related to the build/deploy process.
Notable files
.babelrc
- Babel configuration..eslintignore
- List of files/directories eslint will ignore (similar to .gitignore)..eslintrc
- Eslint configuration..sentryclirc
- Sentry configuration used by webpack to configure a new release on sentry.- Do not change the line
token = <token>
, as this placeholder is used by AppVeyor to insert the sentry api key.
- Do not change the line
.stylelintrc
- Stylelint configuration.CHANGELOG.md
- Collection of changes made to the project. Insert your changes here.jest.config.js
- jest configuration.jest.setup.js
- Script file that will run before jest executes the tests, this includes enzyme setup, polyfills and other useful snippets.webpack.config.js
- Webpack configuration.
Copyright, license and credits
Code and documentation © PayEx and contributors, released under the MIT License.
Inspired by Bootstrap and Materialize.