Contributing encompasses repository specific requirements, and the global Quipucords contribution guidelines.
Quipucords-UI makes use of
- GitHub's fork and pull workflow.
- A linear commit process and rebasing.
Instead of relying on GitHub merge commits and squashing, we recommend breaking down changes into smaller, independent commits.
Linear commit history for Quipucords-UI simplifies understanding and syncing changes across branches. Do not use merge commits. Always use fast-forward rebase.
New changes must be made in a branch and be submitted via GitHub pull requests. PRs should target merging to main
.
All development work should be handled through GitHub's fork and pull workflow.
When multiple developers are contributing features, development pull requests (PRs) should be opened against the main
branch.
If your pull request work contains any of the following warning signs
- out of sync commits (is not rebased against the
base branch
)- poorly structured commits and messages
- any one commit relies on other commits to work at all, in the same pull request
- dramatic file restructures that attempt complex behavior
- missing, relaxed, or removed unit tests
- dramatic unit test snapshot updates
- affects any file not directly associated with the issue being resolved
- affects "many" files
You may be encouraged to restructure your commits to help in review.
Your pull request should contain Git commit messaging that follows the use of conventional commit types to provide consistent history and help generate CHANGELOG.md updates.
Commit messages follow three basic guidelines
-
No more than
65
characters for the first line -
If your pull request has more than a single commit you should include the pull request number in your message using the below format. This additional copy is not counted towards the
65
character limit.[message] (#1234)
You can also include the pull request number on a single commit, but GitHub will automatically apply the pull request number when the
squash
button is used on a pull request. -
Commit message formats follow the structure
<type>(<scope>): <issue number><description>
Where
- Type = the type of work the commit resolves.
- Basic types include
feat
(feature),fix
,chore
,build
. - See conventional commit types for additional types.
- Basic types include
- Scope = optional area of code affected.
- Can be a directory or filenames
- Does not have to encompass all file names affected
- Issue number = the Jira issue number
- Currently, the prefix
dis-[issue number]
can be used in place ofdiscovery-[issue number]
- Currently, the prefix
- Description = what the commit work encompasses
Example
feat(scans): dis-123 activate foo against bar
- Type = the type of work the commit resolves.
Not all commits need an issue number. But it is encouraged you attempt to associate a commit with an issue for tracking. In a scenario where no issue is available exceptions can be made for
fix
,chore
, andbuild
.
Creating a pull request activates the following checks through GitHub actions.
- Commit message linting, see commit_lint.yml
- Pull request code linting, unit tests and repo-level integration tests, see integration.yml
For additional information on failures for
- Commit messages, see Pull request commits, messaging
- Code documentation, see Updating code documentation
- Pull request code, see Updating unit tests during development
To resolve failures for any GitHub actions make sure you first review the results of the test by clicking the
checks
tab on the related pull request.Caching for GitHub actions and NPM packages is active. This caching allows subsequent pull request updates to avoid reinstalling yarn dependencies.
Occasionally test failures can occur after recent NPM package updates either in the pull request itself or in a prior commit to the pull request. The most common reason for this failure presents when a NPM package has changed its support for different versions of NodeJS.
If test failures are happening shortly after a NPM package update you may need to clear the GitHub actions cache and restart the related tests.
quipucords-ui uses GitHub releases, and our GitHub automation automatically builds and attaches artifacts to a release once its tag is created. See integration.yml for implementation details and Build workflow for the history of workflow runs.
To create a new release, use yarn
to update version details, and open a PR to merge those changes to main
using the following process.
-
Within the repo, confirm you're on a new branch from the latest
main
, and useyarn
to update the version:git checkout main && git pull # to ensure you have the latest changes git checkout -b your-release-branch-name # please use an appropriate branch name here yarn # to ensure that packages are installed yarn release --dry-run # to review the changes before committing them yarn release # to generate and commit the changes
If you disagree with automatic generated version number, you may override it with the > optional
--override
argument:yarn release --override X.X.X
-
Confirm you now have a release commit with the format
chore(release): X.X.X
that includes changes to:If there are issues with the file updates, please squash or amend any fixes into the single
chore(release): X.X.X
commit. -
Push the SINGLE commit to a new branch on the remote GitHub origin:
git push --set-upstream origin your-release-branch-name
-
Open a PR in GitHub for your branch to merge into
main
. Get approvals, and merge. -
Using the GitHub releases page:
- Draft a new release from
main
, and confirm it references your latestchore(release): X.X.X
commit hash. - Create the new tag using the SAME semver version created by the release commit, i.e.
X.X.X
.
To avoid issues with inconsistent tags, please use the GitHub releases interface. Do not manually create release tags using
git
. - Draft a new release from
Our schedule for updating NPMs
- dependabot running once a month on low level packages that require only testing confirmation to pass
- 1x a month: running our aggregated dependency update script for all low level packages that require only testing confirmation
$ yarn build:deps
- 1x a month: running updates on NPMs that require additional visual confirmation, this includes...
- dependency-name: "@patternfly/*"
To update packages in bulk there are 2 pre-defined paths, "basic" and "core".
It is highly discouraged that you rely on updating the
yarn.lock
file only. This creates long-term issues when NPM references inpackage.json
potentially require specific dependencies, or have built around specific package functionality that could be inadvertently altered by updating a dependencies' dependency. Updatepackage.json
packages instead.To review where a NPM package resource parent in
package.json
is... within the repo context run$ npm ls [package name]
. This can help provide you with a dependency tree of resources inpackage.json
that should be updated.
- Clone the repository locally, or bring your fork up-to-date with the
main
branch. Make sure development tooling is installed. - Open a terminal instance in the repository context and run
This will cycle through ALL basic NPM dependencies, running both unit tests, build and local integration checks. If any errors are throw the package update is skipped.
$ yarn build:deps
- After the updates have completed YOU MUST VISUALLY CONFIRM the updates were successful by running both local development start scripts.
- Visually confirm that local development still functions and can be navigated with...
- Start VPN, and make sure Docker/Podman is running.
- Run
$ yarn start
- Visually confirm that staging development still functions and can be navigated with...
- Start VPN, and make sure Docker/Podman is running.
- Run
$ yarn start:stage
- Visually confirm that local development still functions and can be navigated with...
- After you've confirmed everything is functioning correctly, check and commit the related changes to
package.json
andyarn.lock
, then open a pull request towards themain
branch.
If any part of the "basic path" process fails you'll need to figure out which NPM is the offender and remove it from the update. OR resolve to fix the issue since future updates will be affected by skipping any package update. A
dependency-update-log.txt" file is generated in the root of the repository after each run of
$ yarn build:deps` this should contain a listing of the skipped packages.
- Clone the repository locally, or bring your fork up-to-date with the
main
branch. Make sure development tooling is installed. - Open a terminal instance in the repository context and run
This will cycle through ALL core NPM dependencies, running both unit tests, build and local integration checks. If any errors are throw the package update is skipped.
$ yarn build:deps-core
- After the updates have completed YOU MUST VISUALLY CONFIRM the updates were successful by running both local development start scripts.
- Visually confirm that local development still functions and can be navigated with...
- Start VPN, and make sure Docker/Podman is running.
- Run
$ yarn start
- Visually confirm that local development still functions and can be navigated with...
- Visually confirm that staging development still functions and can be navigated with...
- Start VPN, and make sure Docker/Podman is running.
- Run
$ yarn start:stage
- After you've confirmed everything is functioning correctly, check and commit the related changes to
package.json
andyarn.lock
, then open a pull request towards themain
branch.
If any part of the "core path" process fails you'll need to figure out which NPM is the offender and remove it from the update. OR resolve to fix the issue since future updates will be affected by skipping potentially any package update. A
dependency-update-log.txt" file is generated in the root of the repository after each run of
$ yarn build:deps-core` this should contain a listing of the skipped packages.
This is the slowest part of package updates. If any packages are skipped during the "basic" and "core" automation runs. Those packages will need to be updated manually.
- Clone the repository locally, or bring your fork up-to-date, with the
main
branch. Make sure development tooling is installed. - Remove/delete the
node_modules
directory (there may be differences between branches that create package alterations) - Run
To re-install the baseline packages.
$ yarn
- Start working your way down the list of
dependencies
anddevDependencies
inpackage.json
. It is normal to start on thedev-dependencies
since the related NPMs support build process. Build process updates, short of a semver major/minor, generally do not break the application.Some text editors fill in the next available NPM package version when you go to modify the package version. If this isn't available you can always use NPM directly... start searching =).
- After each package version update in
package.json
you'll run the follow scripts$ yarn test
, if it fails you'll need to run$ yarn test:dev
and update the related tests$ yarn build
, if it fails you'll need to run$ yarn test:integration-dev
and update the related tests- Make sure Docker/Podman is running, then type
$ yarn start
. Confirm that staging run is still accessible and that no design alterations have happened. Fix accordingly. - Make sure Docker/Podman is running, then type
$ yarn start:stage
. Confirm that staging run is still accessible and that no design alterations have happened. Fix accordingly.
- If the package is now working commit the change and move on to the next package.
- If the package fails, or you want to skip the update, take the minimally easy path and remove/delete
node_modules
then rollbackyarn.lock
BEFORE you run the next package update.
- If the package fails, or you want to skip the update, take the minimally easy path and remove/delete
There are alternatives to resetting
node_modules
, we're providing the most direct path.Not updating a package is not the end-of-the-world. A package is not going to randomly break because you haven't updated to the latest version.
Security warnings on NPM packages should be reviewed on a "per-alert basis" since they generally do not make a distinction between build resources and what is within the applications compiled output. Blindly following a security update recommendation is not always the optimal path.
- Webpack configuration. The build uses configuration combined with NPM scripts found in
package.json
.- Webpack build files
- GitHub Actions
- Action files
- Related script files
Before developing you'll need to install:
- NodeJS and NPM
- Docker
- And Yarn
The tooling for Quipucords-UI is Mac OS
centered.
While some aspects of the tooling have been expanded for Linux there may still be issues. It is encouraged that OS tooling
changes are contributed back while maintaining existing Mac OS
functionality.
If you are unable to test additional OS support it is imperative that code reviews take place before integrating/merging build changes.
The Quipucords-UI build attempts to align to the current NodeJS LTS version. It is possible to test future versions of NodeJS LTS. See CI Testing for more detail.
Setting Docker up on a Mac? Install the appropriate package. Confirm everything installed correctly by trying these steps.
- In a terminal instance run
$ docker run hello-world
Reference the Docker documentation for additional installation help.
Setting Docker up on a Linux machine may include additional steps.
Reference the Docker documentation for additional installation help.
Once you've installed NodeJS you can use NPM to perform the Yarn install
$ npm install yarn -g
"dotenv" files contain shared configuration settings across the Quipucords-UI code and build structure. These settings are imported through helpers, or through other various process.env.[dotenv parameter names]
within the code or build.
Before you can start any local development you need to relax permissions associated with the platform. This
affects various aspects of both local
and stage
development.
- Create a local dotenv file in the root of
Quipucords-UI
called.env.local
and add the following contentsREACT_APP_DEBUG_MIDDLEWARE=true
The dotenv files are structured to cascade each additional dotenv file settings from a root .env
file.
.env = base dotenv file settings
.env.local = a gitignored file to allow local settings overrides
.env -> .env.development = local run development settings that enhances the base .env settings file
.env -> .env.staging = local run staging settings that enhances the base .env settings file
.env -> .env.production = build modifications associated with all environments
.env -> .env.production.local = a gitignored, dynamically generated build modifications associated with all environments
.env -> .env.test = testing framework settings that enhances the base .env settings file
Technically all dotenv parameters come across as strings when imported through
process.env
. It is important to cast them accordingly if "type" is required.
dotenv parameter | definition |
---|---|
REACT_APP_AUTH_TOKEN | A static string associated with overriding the assumed UI/application token name |
REACT_APP_DEBUG_MIDDLEWARE | A static boolean that activates the console state debugging messages associated with Redux |
Technically all dotenv parameters come across as strings when imported through
process.env
. It is important to cast them accordingly if "type" is required.
dotenv parameter | definition |
---|---|
REACT_APP_UI_VERSION | A dynamic string reference to the build populated package.json version reference |
REACT_APP_UI_NAME | A static string reference similar to the application name |
REACT_APP_UI_SHORT_NAME | A static string reference to a shortened display version of the application name |
REACT_APP_UI_SENTENCE_START_NAME | A static string reference to the "sentence start" application name |
REACT_APP_UI_BRAND_NAME | A static string reference similar to the official application name |
REACT_APP_UI_BRAND_SHORT_NAME | A static string reference to a shortened official display version of the application name |
REACT_APP_UI_BRAND_SENTENCE_START_NAME | A static string reference to the official "sentence start" application name |
REACT_APP_UI_BRAND | A dynamic boolean reference used in building the official brand version of Quipucords-UI |
REACT_APP_AUTH_TOKEN | A static string reference to the authentication token |
REACT_APP_AUTH_HEADER | A static string reference to the authentication header |
REACT_APP_AJAX_TIMEOUT | A static number reference to the milliseconds used to timeout API requests |
REACT_APP_TOAST_NOTIFICATIONS_TIMEOUT | A static number reference to the milliseconds used to hide toast notifications |
REACT_APP_POLL_INTERVAL | A static number reference to the milliseconds used in view polling |
REACT_APP_CONFIG_SERVICE_LOCALES_DEFAULT_LNG | A static string reference to the UI/application default locale language |
REACT_APP_CONFIG_SERVICE_LOCALES_DEFAULT_LNG_DESC | A static string reference to the UI/application default locale language |
REACT_APP_CONFIG_SERVICE_LOCALES | A static string reference to a JSON resource for available UI/application locales |
REACT_APP_CONFIG_SERVICE_LOCALES_PATH | A static string reference to the JSON resources for available UI/application locale strings |
REACT_APP_CONFIG_SERVICE_LOCALES_EXPIRE | A static number reference to the milliseconds the UI/application locale strings/files expire |
REACT_APP_CREDENTIALS_SERVICE | A static string reference to the API spec |
REACT_APP_FACTS_SERVICE | A static string reference to the API spec |
REACT_APP_REPORTS_SERVICE | A static string reference to the API spec |
REACT_APP_REPORTS_SERVICE_DETAILS | A static string reference to the API spec |
REACT_APP_REPORTS_SERVICE_DEPLOYMENTS | A static string reference to the API spec |
REACT_APP_REPORTS_SERVICE_MERGE | A static string reference to the API spec |
REACT_APP_SCANS_SERVICE | A static string reference to the API spec |
REACT_APP_SCAN_JOBS_SERVICE_START_GET | A static string reference to the API spec |
REACT_APP_SCAN_JOBS_SERVICE | A static string reference to the API spec |
REACT_APP_SCAN_JOBS_SERVICE_CONNECTION | A static string reference to the API spec |
REACT_APP_SCAN_JOBS_SERVICE_INSPECTION | A static string reference to the API spec |
REACT_APP_SCAN_JOBS_SERVICE_PAUSE | A static string reference to the API spec |
REACT_APP_SCAN_JOBS_SERVICE_CANCEL | A static string reference to the API spec |
REACT_APP_SCAN_JOBS_SERVICE_RESTART | A static string reference to the API spec |
REACT_APP_SCAN_JOBS_SERVICE_MERGE | A static string reference to the API spec |
REACT_APP_SOURCES_SERVICE | A static string reference to the API spec |
REACT_APP_USER_SERVICE | A static string reference to the API spec |
REACT_APP_USER_SERVICE_CURRENT | A static string reference to the API spec |
REACT_APP_USER_SERVICE_LOGOUT | A static string reference to the API spec |
REACT_APP_STATUS_SERVICE | A static string reference to the API spec |
This is a local run designed to function with minimal resources and a mock API.
- Confirm you've installed all recommended tooling
- Confirm the repository name has no blank spaces in it. If it does replace that blank with a dash or underscore, Docker has issues with unescaped parameter strings.
- Confirm you've installed resources through yarn
- Create a local dotenv file called
.env.local
in the root of Quipucords-UI, and add the following contentsREACT_APP_DEBUG_MIDDLEWARE=true
- Make sure Docker/Podman is running
- Open a couple of instances of Terminal and run...
and, optionally,
$ yarn start
$ yarn test:dev
- Make sure your browser opened around the domain
https://localhost:3000/
- Start developing...
This is an authenticated local run that has the ability to run against a containerized API.
- Confirm you've installed all recommended tooling
- Confirm the repository name has no blank spaces in it. If it does replace that blank with a dash or underscore, Docker has issues with unescaped parameter strings.
- Confirm you've installed resources through yarn
- Create a local dotenv file called
.env.local
in the root of Quipucords-UI, and add the following contentsREACT_APP_DEBUG_MIDDLEWARE=true
- Make sure Docker/Podman is running
- Open a couple of instances of Terminal and run...
and, optionally,
$ yarn start:stage
$ yarn test:dev
- Make sure you open your browser around the domain
https://localhost:5001/
You may have to scroll, but the terminal output will have some available domains for you to pick from.
- Log in. (You'll need mock credentials, reach out to the development team)
- Start developing...
This project makes use of reserved DOM attributes and string identifiers used by the testing team.
Updating elements with these attributes, or settings, should be done with the knowledge "you are affecting" the testing team's ability to test. And it is recommended you coordinate with the testing team before altering these attributes, settings.
- Attribute
data-ouia-component-id
data-ouia-component-id=""
is preferred way of identifying elements by testing team.- Most of the time, React prop is
ouiaId
. Some PatternFly elements don't support it, in which case you can use standard DOM propdata-ouia-component-id
,data-test
,name
orid
. - Use
ouiaId
even if it seems to duplicate value ofname
or another attribute. - See PatternFly documentation on OUIA.
- Attribute
data-test
- DOM attributes with
data-test=""
are used by the testing team as a means to identify specific DOM elements. - To use simply place
data-test="[your-id-coordinated-with-testing-team]
" onto a DOM element.
- DOM attributes with
This repository has interdependency on the Quipucords responsitory.
In order to have GUI developer access to the login and logout aspects of Quipucords we store the Django template files here ./templates/*.
Important!
- This templates directory is required as part of the build process. Removing
./templates
directory will break the production build.- Updating the templates requires minimal understand of html, plus some minor recognition of templating languages. If needed checkout out the Django template structure reading.
- We use a shell script token string replacement during the build process for the application display name. If you see [UI_NAME] within the templates, be aware.
- The build script for directly manipulating the templates is here, ./scripts/post.sh
The brand build updates aspects of the application name across the React and Django templates, think Quipucords versus Discovery.
To handle a branded aspect of the build, instead of $ yarn build
run
$ yarn build:brand
You can apply overrides during local development by adding a .env.local
(dotenv) file in the repository root directory.
Once you have made the dotenv file and/or changes, like the below "debug" flags, restart the project and the flags should be active.
Any changes you make to the .env.local
file should be ignored with .gitignore
.
This project makes use of React & Redux. To enable Redux browser console logging add the following line to your .env.local
file.
REACT_APP_DEBUG_MIDDLEWARE=true
Blindly updating unit test snapshots is not recommended. Within this code-base snapshots have been created to specifically call out when updates happen. If a snapshot is updating, and it is unexpected, this is our first line of checks against bugs/issues.
To run the unit tests with a watch during development you'll need to open an additional terminal instance, then run
$ yarn test:dev
To update snapshots from the terminal run
$ yarn test:dev
From there you'll be presented with a few choices, one of them is "update", you can then hit the "u" key. Once the update script has run you should see additional changed files within Git, make sure to commit them along with your changes or continuous integration testing will fail.
To check the coverage report from the terminal run
$ yarn test
If you're having trouble getting an accurate code coverage report, or it's failing to provide updated results (i.e. you renamed files) you can try running
$ yarn test:clearCache
To run tests associated with checking build output run
$ yarn build
$ yarn test:integration
To update snapshots from the terminal run
$ yarn test:integration-dev