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.
#### Branch syncing
+
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`.
@@ -24,17 +28,19 @@ New changes must be made in a branch and be submitted via GitHub pull requests.
All development work should be handled through GitHub's fork and pull workflow.
#### Setting up a pull request
+
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
+>
+> - 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.
@@ -44,8 +50,10 @@ Your pull request should contain Git commit messaging that follows the use of [c
to provide consistent history and help generate [CHANGELOG.md](./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)
```
@@ -55,10 +63,13 @@ Commit messages follow three basic guidelines
`squash` button is used on a pull request.
- Commit message formats follow the structure
+
```
():
```
+
Where
+
- Type = the type of work the commit resolves.
- Basic types include `feat` (feature), `fix`, `chore`, `build`.
- See [conventional commit types](https://www.conventionalcommits.org/) for additional types.
@@ -70,19 +81,24 @@ Commit messages follow three basic guidelines
- Description = what the commit work encompasses
Example
+
```
feat(scans): dis-123 activate foo against bar
```
-> 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`, and `build`.
+
+ > 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`, and `build`.
#### Pull request test failures
+
Creating a pull request activates the following checks through GitHub actions.
+
- Commit message linting, see [commit_lint.yml](./.github/workflows/commit_lint.yml)
- Pull request code linting, unit tests and repo-level integration tests, see [integration.yml](./.github/workflows/integration.yml)
For additional information on failures for
+
- Commit messages, see [Pull request commits, messaging](#pull-request-commits-messaging)
- Code documentation, see [Updating code documentation]()
- Pull request code, see [Updating unit tests during development]()
@@ -108,9 +124,11 @@ For additional information on failures for
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](https://github.com/quipucords/quipucords-ui/blob/main/.github/workflows/integration.yml) for implementation details and [Build workflow](https://github.com/quipucords/quipucords-ui/actions/workflows/integration.yml?query=event%3Apush) for the history of workflow runs.
#### Release artifacts
+
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.
1. Within the repo, confirm you're on a new branch from the latest `main`, and use `yarn` 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
@@ -120,20 +138,25 @@ To create a new release, use `yarn` to update version details, and open a PR to
```
> If you disagree with automatic generated version number, you may override it with the > optional `--override` argument:
+ >
> ```
> yarn release --override X.X.X
> ```
+
2. Confirm you now have a release commit with the format `chore(release): X.X.X` that includes changes to:
+
- [`package.json`](./package.json)
- [`CHANGELOG.md`](./CHANGELOG.md)
If there are issues with the file updates, please squash or amend any fixes into the single `chore(release): X.X.X` commit.
+
3. Push the **SINGLE** commit to a new branch on the remote GitHub origin:
```
git push --set-upstream origin your-release-branch-name
```
4. Open a PR in GitHub for your branch to merge into `main`. Get approvals, and merge.
5. Using the [GitHub releases page](https://github.com/RedHatInsights/quipucords-ui/releases):
+
1. Draft a new release from `main`, and confirm it references your latest `chore(release): X.X.X` commit hash.
2. Create the new tag using the **SAME** semver version created by the release commit, i.e. `X.X.X`.
@@ -146,14 +169,17 @@ To create a new release, use `yarn` to update version details, and open a PR to
NPM maintenance
#### Cycle for updating NPMs
+
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/*"
+ - dependency-name: "@patternfly/\*"
#### Process for updating NPMs
+
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 in `package.json` potentially require specific
@@ -166,57 +192,62 @@ To update packages in bulk there are 2 pre-defined paths, "basic" and "core".
1. Clone the repository locally, or bring your fork up-to-date with the `main` branch. [Make sure development tooling is installed](#install-tooling).
1. Open a terminal instance in the repository context and run
- ```
- $ yarn build:deps
- ```
+ ```
+ $ yarn build:deps
+ ```
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.
1. 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...
- 1. Start VPN, and make sure Docker/Podman is running.
- 1. Run
- ```
- $ yarn start
- ```
+ 1. Start VPN, and make sure Docker/Podman is running.
+ 1. Run
+ ```
+ $ yarn start
+ ```
- Visually confirm that staging development still functions and can be navigated with...
- 1. Start VPN, and make sure Docker/Podman is running.
- 1. Run
- ```
- $ yarn start:stage
- ```
+ 1. Start VPN, and make sure Docker/Podman is running.
+ 1. Run
+ ```
+ $ yarn start:stage
+ ```
1. After you've confirmed everything is functioning correctly, check and commit the related changes to `package.json` and `yarn.lock`, then open a pull request towards the `main` 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.
+ > 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.
##### Core NPM updates
+
1. Clone the repository locally, or bring your fork up-to-date with the `main` branch. [Make sure development tooling is installed](#install-tooling).
1. Open a terminal instance in the repository context and run
- ```
- $ yarn build:deps-core
- ```
+ ```
+ $ yarn build:deps-core
+ ```
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.
1. 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...
- 1. Start VPN, and make sure Docker/Podman is running.
- 1. Run
- ```
- $ yarn start
- ```
- - Visually confirm that staging development still functions and can be navigated with...
1. Start VPN, and make sure Docker/Podman is running.
1. Run
```
- $ yarn start:stage
+ $ yarn start
```
+
+- Visually confirm that staging development still functions and can be navigated with...
+ 1. Start VPN, and make sure Docker/Podman is running.
+ 1. Run
+ ```
+ $ yarn start:stage
+ ```
+
1. After you've confirmed everything is functioning correctly, check and commit the related changes to `package.json` and `yarn.lock`, then open a pull request towards the `main` 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.
+ > 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.
##### Manual NPM updates
+
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.
+
1. Clone the repository locally, or bring your fork up-to-date, with the `main` branch. [Make sure development tooling is installed](#install-tooling).
1. Remove/delete the `node_modules` directory (there may be differences between branches that create package alterations)
1. Run
@@ -233,9 +264,9 @@ This is the slowest part of package updates. If any packages are skipped during
- 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.
1. 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 rollback `yarn.lock` **BEFORE** you run the next package update.
-> 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.
+ > 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.
@@ -253,21 +284,23 @@ This is the slowest part of package updates. If any packages are skipped during
- GitHub Actions
- Action files
- [`./.github/workflows`](.github/workflows)
- - Related script files
- - [`./.scripts/actions.commit.js`](./scripts/actions.commit.js)
-
+ - Related script files - [`./.scripts/actions.commit.js`](./scripts/actions.commit.js)
+
## Development
+
Install tooling
Before developing you'll need to install:
-* [NodeJS and NPM](https://nodejs.org/)
-* [Docker](https://docs.docker.com/desktop/)
- * Alternatively, you can try [Podman](https://github.com/containers/podman). [Homebrew](https://brew.sh/) can be used for the install `$ brew install podman`
-* And [Yarn](https://yarnpkg.com)
+
+- [NodeJS and NPM](https://nodejs.org/)
+- [Docker](https://docs.docker.com/desktop/)
+ - Alternatively, you can try [Podman](https://github.com/containers/podman). [Homebrew](https://brew.sh/) can be used for the install `$ brew install podman`
+- And [Yarn](https://yarnpkg.com)
#### OS support
+
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
@@ -276,10 +309,13 @@ 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.
#### NodeJS and NPM
+
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.
#### Docker and Mac
+
Setting [Docker](https://docs.docker.com/desktop/) up on a Mac? Install the appropriate package. Confirm everything installed correctly by trying these steps.
+
1. In a terminal instance run
```
$ docker run hello-world
@@ -288,17 +324,21 @@ Setting [Docker](https://docs.docker.com/desktop/) up on a Mac? Install the appr
Reference the Docker documentation for additional installation help.
#### Docker and Linux
+
Setting Docker up on a Linux machine may include additional steps.
-* [Docker on Linux](https://docs.docker.com/desktop/install/linux-install/)
+
+- [Docker on Linux](https://docs.docker.com/desktop/install/linux-install/)
Reference the Docker documentation for additional installation help.
#### Yarn
+
Once you've installed NodeJS you can use NPM to perform the [Yarn](https://yarnpkg.com) install
- ```
- $ npm install yarn -g
- ```
+```
+$ npm install yarn -g
+```
+
@@ -307,16 +347,19 @@ Once you've installed NodeJS you can use NPM to perform the [Yarn](https://yarnp
"dotenv" files contain shared configuration settings across the Quipucords-UI code and build structure. These settings are imported through [helpers](./src/common/helpers.js), or through other various `process.env.[dotenv parameter names]` within the code or build.
#### Setup basic dotenv files
+
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.
1. Create a local dotenv file in the root of `Quipucords-UI` called `.env.local` and add the following contents
- ```
- REACT_APP_DEBUG_MIDDLEWARE=true
- ```
+ ```
+ REACT_APP_DEBUG_MIDDLEWARE=true
+ ```
#### Advanced dotenv files
+
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
@@ -331,13 +374,11 @@ The dotenv files are structured to cascade each additional dotenv file settings
> 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 |
-
##### Current directly available _build_ dotenv parameters
> Technically all dotenv parameters come across as strings when imported through `process.env`. It is important to cast them accordingly if "type" is required.
@@ -389,15 +430,16 @@ The dotenv files are structured to cascade each additional dotenv file settings
Local and staging development
#### Start writing code with local run
+
This is a local run designed to function with minimal resources and a mock API.
1. Confirm you've installed all recommended tooling
1. 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.
1. Confirm you've installed resources through yarn
1. Create a local dotenv file called `.env.local` in the root of Quipucords-UI, and add the following contents
- ```
- REACT_APP_DEBUG_MIDDLEWARE=true
- ```
+ ```
+ REACT_APP_DEBUG_MIDDLEWARE=true
+ ```
1. Make sure Docker/Podman is running
1. Open a couple of instances of Terminal and run...
```
@@ -411,24 +453,25 @@ This is a local run designed to function with minimal resources and a mock API.
1. Start developing...
#### Start writing code with staging
+
This is an authenticated local run that has the ability to run against a containerized API.
1. Confirm you've installed all recommended tooling
1. 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.
1. Confirm you've installed resources through yarn
1. Create a local dotenv file called `.env.local` in the root of Quipucords-UI, and add the following contents
- ```
- REACT_APP_DEBUG_MIDDLEWARE=true
- ```
+ ```
+ REACT_APP_DEBUG_MIDDLEWARE=true
+ ```
1. Make sure Docker/Podman is running
1. Open a couple of instances of Terminal and run...
- ```
- $ yarn start:stage
- ```
+ ```
+ $ yarn start:stage
+ ```
and, optionally,
- ```
- $ yarn test:dev
- ```
+ ```
+ $ yarn test:dev
+ ```
1. 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.
1. Log in. (You'll need mock credentials, reach out to the development team)
@@ -436,12 +479,13 @@ This is an authenticated local run that has the ability to run against a contain
-
Reserved CSS classNames, and attributes
#### Reserved testing attributes
+
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.
@@ -462,38 +506,47 @@ This project makes use of reserved DOM attributes and string identifiers used by
This repository has interdependency on the [Quipucords responsitory](https://github.com/quipucords/quipucords).
#### Django templates, login and logout
+
In order to have GUI developer access to the login and logout aspects of [Quipucords](https://github.com/quipucords/quipucords) we store
-the Django template files here [./templates/*](./templates/base.html).
+the Django template files here [./templates/\*](./templates/base.html).
> 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](https://docs.djangoproject.com/en/2.1/topics/templates/).
> - 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](./scripts/post.sh)
#### Brand build
+
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
- ```
+
+```
+$ yarn build:brand
+```
+