Hi, glad you are here all contributions are very much welcome!
Before you start Contributing to Canopy it is worth familiarising yourself with the best practice guidelines.
Please do raise an issue or discussion before starting a piece of work. Our contributors can help provide guidance to make sure your effort isn't wasted. It is important that the development and design implementations stay in sync and that the codebase remains consistent. This will help to give the codebase a long life and remain intuitive for those using it.
Canopy uses Storybook to enable components to be developed in isolation. If you are creating a new component or directive a corresponding story file will be needed.
Running npm start will run storybook locally, this will hot reload any changes and is the most seamless way to modify or create existing components.
Pull requests are deployed manually to GitHub Pages by the Core or Regular Contributors. Once the deployment has completed successfully the pull request will be updated with the environment details.
The master branch is also deployed to GitHub Pages, this currently provides the most up-to-date documentation for the latest version.
https://legal-and-general.github.io/canopy
Run npm run build to build the library and global styles.
The build artifacts will be stored in the dist/ directory.
A test application is located in the projects/canopy-test-app folder. This application helps to capture any issues with exported modules. Run npm run build:test-app to build the test application, this happens automatically as part of the pull request pipeline.
The test application includes a test page which contains all of the Canopy components to ensure that they layout correctly. This page is also accessible in storybook via the main navigation, where possible all new components should be added to the test page.
Run npm test to execute the library unit tests, this step is also run as part of the pull request pipeline.
Run npm run lint to execute the library unit tests, this step is also run as part of the pull request pipeline.
Current linting includes
eslintandprettierfor typescript, javascript and html filesstylelintandprettierfor scss filesprettierfor json files
This repository is set up to work with the angular version of conventional commits.
A git commit-msg hook will lint your commits to ensure they are of the correct format. To make it easy to follow the correct format you can npm run commit which will use the commitizen cli to run you through the process.
The commit message format is important as it is what drives the semantic versioning. Versioning is currently carried out by the semantic release node module. On merging to the master branch, semantic release will scan the commit messages and determine the next version. It will also tag, package and deploy this version to the GitHub registry.
Be particularly aware of any changes which may be deemed a breaking change. Refer to our guide of what is and is not considered a breaking change
The format for breaking changes is outlined on the convention commit docs
Whenever introducing a breaking change consider using the next branch. Refer to the next docs.
Fix
fix(release): need to depend on latest rxjs and zone.js
The version in our package.json gets copied to the one we publish, and users need the latest of these.
Breaking change
feat(button): allow provided config object to extend other configs
BREAKING CHANGE: `extends` key in config file is now used for extending other config files
To ensure that changes come from an entrusted source all commits must be signed, Follow the steps below to setup commit signing.
-
Make sure the email address you use, matches your local git email address (
git config --get user.email) and that of your GitHub account. If not, either change your git email address or add this address to your GitHub account.
Branches should be in kebab-case format.
The repository is set up with a pre-push hook that will prevent the user from pushing if the branch name doesn't match the correct format.
Pull requests require two successful approvals before they can be merged. One review must be from a CODEOWNER. We also require that developers working on a specific project seek review from someone on a different project. The aim being that by removing any immediate delivery pressure we can ensure a high level of quality and negate the risk of factions forming within the codebase, currently we cannot automate this process and so it must be based on trust.
Code Owners are chosen based on a history of consistent contributions. Code Owners should have an understanding of the current issues list and have a wider view of the technical direction of the project. They should help to steer technical direction via pull request reviews and be focused on the longer term success of the project. Code Owners are not limited to being from our particular organisation.
The build is currently handled by Github Actions, the config for which is checked into the .github directory. The build will run on every pull request and run standard verification tasks e.g. linting, unit testing, test build. The build will need to be green in order for a pull request to pass.
To add a new SVG icon to Canopy simply add the file to either the icons or brand-icons folder within assets.
When committing the new icons lint-staged will run and generate all the ts files automatically.
The Roboto font is stored in /projects/canopy/src/assets/fonts/roboto as normal and is included in the distributed Canopy package.
The Lyon font files are stored in /assets/fonts and omitted from the distributed package via the Webpack config. The css-loader options prevent it from transforming any URL referencing the Lyon font. This means the path will stay as relative to the base URL of the consuming application (/assets/fonts), therefore looking in the assets directory of consuming app.
For more info, see the fonts section in USAGE.md.
The @angular/cdk can be used as long as only the necessary functionality is imported.
The dependency updates are currently handled by Dependabot.