14 KiB
Landmark Credit Union Repo Application
This readme outlines the developer process, basic coding style guide and provides guidance and details around the technical approach to the user interface. You should always review and update this document to encompass your changes.
Getting Started
Before you can work with the code, build it, or deploy it you must setup your development environment. The required environment is Git, Node, and something to work with Typescript.
This environment code has been wrapped up into a Powershell script that should run on any Windows 10 machine and produce a viable development environment to carry you through this guide.
The script is available in the root of this directory as setup-env.ps1.
You should start by reviewing and possibly running that script if needed.
Working With The Code
Code is checked out from the Azure DevOps Repository, which is currently [https://landmarkcu.visualstudio.com/Repo/_git/LCU.WebApps.Collections.RepoClient] with the back end code located at [https://landmarkcu.visualstudio.com/Repo/_git/LCU.API.Collections.RepoApi].
Work should be done in a branch from Develop. In the shared folder there is a software development process document that talks about this, you should start there. A brief introduction will be included here.
Start by checking out the repository, and specifically the develop branch. You should be branching off of develop with your own working branch. When you are complete, you will create a pull request within Azure DevOps here: [https://landmarkcu.visualstudio.com/Repo/_git/LCU.WebApps.Collections.RepoClient/pullrequests]
Before submitting your pull request, review the following:
- Did you commit with commitizen?
git cz(see below) - Did you add all needed unit testing, and ensure all existing tests are passing?
- Have you run the e2e tests and ensured they all pass?
In order to work and submit code, the project will need to be built and run. Instructions follow. Generally the project doesn't need to be built, just run locally. However, running a production build after major changes will ensure the production build is still working before CI runs.
Finally, you'll need to know React, Redux and Typescript.
Learning React, Redux, Typescript, etc
Docs:
React, Redux And Typescript have great quick-start guides that walk through their features step by step with examples:
- React: https://reactjs.org/docs/getting-started.html
- Redux: https://redux.js.org/introduction/core-concepts
- Typescript: https://www.typescriptlang.org/docs/home.html
Useful Resources:
1. https://medium.com/@tkssharma/understanding-redux-react-in-easiest-way-part-1-81f3209fc0e5
2. https://blog.usejournal.com/using-react-with-redux-and-typescript-c7ec48c211f6
3. https://hackernoon.com/redux-step-by-step-a-simple-and-robust-workflow-for-real-life-apps-1fdf7df46092
4. https://medium.com/naukri-engineering/email-sending-architecture-using-messaging-queue-314a18f8595c
5. https://reactjs.org/docs/higher-order-components.html#convention-maximizing-composability
6. https://blog.logrocket.com/react-redux-connect-when-and-how-to-use-it-f2a1edab2013/
7. https://stackoverflow.com/questions/54154673/react-typescript-redux-connect-function-not-working
8. https://redux.js.org/recipes/structuring-reducers/basic-reducer-structure
Redux in TypeScript Quick Guide
- Know what a Higher Order Component is.
- The types: https://github.com/DefinitelyTyped/DefinitelyTyped/blob/master/types/react-redux/index.d.ts#L59
- Connect is a higher order component used to wrap your component giving it access to state from the store and dispatch actions.
Initial Install Dependencies
Remove node_modules directory if exists.
Remove .npmrc file.
Inside package.json remove dependency "lcu-react-lib": "^2.18.0"
Run npm install
Inside package.json run the "refreshVSToken" script.
Inside package.json add back dependency "lcu-react-lib": "^2.18.0"
Run npm install
From the source control tab of VS Code, Discard changes on the .npmrc file to bring it back into the project code
Build
Run npm run build to build the project with default settings, which for create-react-app is production. The development
server will do a debug build.
Run (Development server)
Run npm start for a dev server. Navigate to https://localhost:3000/. The app will automatically reload if you change any of the source files.
Note that this will run with a proxy in place so that you can contact the web services.
Deploy (QA, UAT, Prod)
Deployments to QA, UAT, and Prod are automatically handled by Azure Dev-Ops. See the additional resources section below; as there is a document outlining the software development process, as well as the cloud setup Azure.
Running unit tests
Run npm run test to run the unit tests interactively, they will re-run whenever you make changes. To simulate
the CI server and run them once, npm run test-ci or set the CI environment variable before running npm run test
Resources
There is additional documentation available within the Landmark shared folders; you should check the files tab under the RepoDB team in Microsoft Teams:
- Architecture Document: Landmark Credit Union - Repo Application - SAD
- This is the software architecture description.
- Site Layout / Reference: Landmark_Site_Reference.XLSX
- This shows urls/locations for source code and deployables and the Azure configuration
- Software Process: landmark_software_process.docx
- Outlines the process for working with the source code.
Suggestion for IDE
- Visual Studio Code
- Webstorm
Other Tools:
Architecture
The best explanation for the architecture can be found by referencing the document listed in the resources section above. However if you are looking to do something specific, here are some tips.
A. Change an environment
- under the src/environments folder there are currently two environment files to specify settings per environment.
- The environment is controlled with process.env.REACT_APP_STAGE, see Configuration.ts
Releases
Releases are handled by anyone on the team with access to Azure DevOps. Generally when a pull request is accepted to develop, that will be automatically built and deployed to QA. The QA application is here: [https://qa-repomanage.landmarkcu.com]. The same is true for the back end / API.
To get to UAT, develop must be merged into the release branch and pushed. This will automatically cause the release branch to be built and the resulting release to be pushed to UAT.
To get to production, release must be merged into master and pushed. This will automatically cause the code to be built and packaged as artifacts. However the release process is manual, and can be done here: [https://landmarkcu.visualstudio.com/Repo/_release]
When creating releases, it's important not to forget to make a release and update the change notes as needed. There is information on creating a release below. An important tip is that on the website you can hover over the Landmark copyright in the bottom center to see the released client version and build stamp.
Setup Commitizen and Produce changelogs and release notes
Commitizen is a command line tool that helps format commit messages with a series of prompts that are used to generate a commit message. We use this tool to standardize our commits for tracking a changelog and producing release notes.
npm install commitizen -gnpm install commitizen --save-dev// Already done for you, skip.npm install cz-conventional-changelog --save-dev// Already done for you, skip.npm install husky --save-dev// Already done for you, skip.npm install --save-dev validate-commit-msg// Already done for you, skip.npm install -g conventional-changelog-cli
Instead of committing with git commit commit with git cz
This will force your messages into the format ():
| Definition | Description |
|---|---|
| feat | A new feature |
| fix | A bug fix |
| docs | Documentation only changes |
| style | Changes that do not affect the meaning of the code (white-space, formatting, missing semi-colons, etc) |
| refactor | A code change that neither fixes a bug nor adds a feature |
| perf | A code change that improves performance |
| test | Adding missing or correcting existing tests |
| chore | Changes to the build process or auxiliary tools and libraries such as documentation generation |
Here is how semantic-release will map these to release types and how it maps to semantic verioning:
| Commit message | Release type |
|---|---|
fix(pencil): stop graphite breaking when too much pressure applied |
Patch Release (PATCH) |
feat(pencil): add 'graphiteWidth' option |
Feature Release (MINOR) |
BREAKING CHANGE: The graphiteWidth option has been removed. The default graphite width of 10mm is always used for performance reasons. |
Breaking Release (MAJOR) |
Produce or update the changelog
You shouldn't need to do this, it should be generated for you when you create a release (below)
- Create changelog from scratch:
conventional-changelog -p angular -i CHANGELOG.md -s -r 0 - Update the changelog:
conventional-changelog -p angular -i CHANGELOG.md -s
Produce a set of release notes and bump version
- Use:
npm run release - You should check the ChangeLog.MD after this and make any corrections.
Resources:
- http://www.nullfactory.net/2017/04/enforce-commit-message-standards-and-generate-changelogs-via-git/
- https://dev.bleacherreport.com/how-we-use-commitizen-to-clean-up-commit-messages-a16790dcd2fd
- http://devboosts.com/2017/03/28/conventional-commits/
- https://medium.com/@LeonardoBrAu/why-git-squash-and-rebase-commits-and-how-we-do-it-87aa17406e21
ADA Compliance
This application is targeting level AA ADA Compliance, here is the checklist you should keep in mind when developing:
- Every image, video file, audio file, plug-in, etc. has an alt tag
- Complex graphics are accompanied by detailed text descriptions
- The alt descriptions describe the purpose of the objects
- If an image is also used as a link, the alt tag describes the graphics and the link destination
- Decorative graphics with no other function have empty alt descriptions (alt=””)
- Data tables have the column and row headers appropriately identified (using the tag)
- Make sure the page does not contain repeatedly flashing images
- Check to make sure the page does not contain a strobe effect
- All scripts and plug-ins and the content within them are accessible to assistive technologies, or else an alternative means of accessing equivalent content is provided
- When form controls are text input fields use the LABEL element
- When text is not available use the title attribute
- Include any special instructions within field labels
- Make sure that form fields are in a logical tab order
- Include a ‘Skip Navigation’ button to help those using text readers
- SVG icons should not focusable by tabbing in IE (utilize
focusable="false"on all icon tags)
Coding tools for ADA Compliance
- Refer to here for help: https://getbootstrap.com/docs/4.0/getting-started/accessibility/
- Refer to here for practical examples: http://www.punkchip.com/aria-basic-findings/
- use aria-label, aria-expanded, and aria-hidden as needed.
- Bootstrap: sr-only, bootstrap provides sr-only so that you can show things to people with screen readers. (sr-only stands for screen readers only)
Style Concerns
-
Select boxes title/default should be "Please Choose" if they do not have a default value.
-
Name your actions with the relevant NOUN in them, don't do GET_ALL, do REPOACCOUNT_GET_ALL.
-
Wherever possible reuse an existing component to keep UI consistent across application.
-
It is best to convert literals to constants at the top of the file. If applicable, move this const to the configuration where it can be easily modified later.
- Always keep the web development checklist in mind: http://webdevchecklist.com/
- You should have unit tests for all components and public functions
- Take your time with naming and ask the team for help; but take naming seriously so that your components and services are recognizable.
- Review the .editorconfig file if you are notices style differences in PRs, resolve any problems with the team.
Libraries
- Redux-router - This router library is used to enable hash routing within the application.
- React-Adal - JWT authentication via Azure AD.
- react-app-polyfill - Add support for IE10/IE11
- react-toastify - Used to notify users of events within the application
FAQ
Q. What the heck is a 'thunk'?
A. https://daveceddia.com/what-is-a-thunk/
Q. I'm running the unit test and I see output like this:
HeadlessChrome 68.0.3440 (Windows 10.0.0) XYZComponent should use the service to add address controls to the form group FAILED [object ErrorEvent] thrown
A. Re-run the tests using npm run test-debug, which will show the full stack trace but not provide code coverage.
Q. What do I need to know about Security?
A. The major security concerns are outlined in the architecture documents in the share (see resources above). The main security mechanism is for Landmark employees, and uses the React-ADAL library to authenticate against Azure AD.
Q. Where was this project started from?
A. This project was bootstrapped with Create React App.