docs: build and release process overview #572

jason-capsule42 · 2024-10-01T03:57:11Z

Alaska Airlines Pull Request

Please include a summary of the change and which issue is fixed. Please also include relevant motivation and context. List any dependencies that are required for this change.

Resolves: # (issue, if applicable)

Summary:

Please summarize the scope of the changes you have submitted, what the intent of the work is and anything that describes the before/after state of the project.

Type of change:

Please delete options that are not relevant.

New capability
Revision of an existing capability
Infrastructure change (automation, etc.)
Other - work out build/release workflow documentation

Checklist:

My update follows the CONTRIBUTING guidelines of this project
I have performed a self-review of my own update

By submitting this Pull Request, I confirm that my contribution is made under the terms of the Apache 2.0 license.

Pull Requests will be evaluated by their quality of update and whether it is consistent with the goals and values of this project. Any submission is to be considered a conversation between the submitter and the maintainers of this project and may require changes to your submission.

Thank you for your submission!

-- Auro Design System Team

Summary by Sourcery

Document the build and release process for Auro components, detailing local development steps, commit procedures, and automated workflows for code integration and release.

Documentation:

Add a new document 'buildRelease.md' that outlines the build and release process for Auro components, including steps for local development, committing changes, and the workflows triggered upon code push and merge.

sourcery-ai · 2024-10-01T03:57:16Z

Reviewer's Guide by Sourcery

This pull request adds a new document, 'buildRelease.md', to the 'docs' directory. The document provides an overview of the build and release process for Auro components, detailing the steps from local development to final release.

Sequence Diagram

sequenceDiagram
    participant Dev as Developer
    participant Local as Local Environment
    participant Git as Git
    participant GH as GitHub
    participant NPM as npm

    Dev->>Local: git clone repository
    Dev->>Local: npm install
    Local->>Git: Install husky hooks
    Dev->>Local: npm run build
    Dev->>Local: npm run build:docs
    Dev->>Git: git commit
    Git->>Local: Run commit linters
    Dev->>GH: Push changes & open PR
    GH->>GH: Run CodeQL workflow
    GH->>GH: Run Test and publish workflow
    GH->>GH: Merge PR
    GH->>GH: Run Semantic release
    GH->>NPM: Publish new version

File-Level Changes

Change	Details	Files
Addition of a new documentation file for build and release process	Outline of local development steps Description of commit process and hooks Explanation of GitHub workflows Details on merge and release processes	`docs/buildRelease.md`

Tips and commands

Interacting with Sourcery

Trigger a new review: Comment @sourcery-ai review on the pull request.
Continue discussions: Reply directly to Sourcery's review comments.
Generate a GitHub issue from a review comment: Ask Sourcery to create an
issue from a review comment by replying to it.

Customizing Your Experience

Access your dashboard to:

Enable or disable review features such as the Sourcery-generated pull request
summary, the reviewer's guide, and others.
Change the review language.
Add, remove or edit custom review instructions.
Adjust other review settings.

Getting Help

Contact our support team for questions or feedback.
Visit our documentation for detailed guides and information.
Keep in touch with the Sourcery team by following us on X/Twitter, LinkedIn or GitHub.

sourcery-ai

Hey @jason-capsule42 - I've reviewed your changes - here's some feedback:

Overall Comments:

Consider adding more specific details about the CI/CD process, including the exact GitHub Actions workflows used and their configurations.
It would be helpful to standardize the document's structure and use more precise language throughout. Consider using a consistent format for each step in the process.
Please clarify the inconsistencies mentioned in the document, such as the build:version script. If possible, standardize these processes across all components.

Here's what I looked at during the review

🟢 General issues: all looks good
🟢 Security: all looks good
🟢 Testing: all looks good
🟢 Complexity: all looks good
🟡 Documentation: 6 issues found

Sourcery is free for open source - if you like our reviews please consider sharing them ✨

_{Help me be more useful! Please click 👍 or 👎 on each comment and I'll use the feedback to improve your reviews.}

docs/buildRelease.md

jason-capsule42 · 2024-10-01T04:09:36Z

docs/buildRelease.md

+            1. `build:test`
+            1. `build:api` 
+            1. `build:docs` 
+            1. `bundler` 


The bundler 100% has to be moved into part of the local dev cycle rather than just release. Any component with complex JS based documentation examples is dependent on the bundler running for it to be able to validate during testing.

To follow through that... if we are already running the bundler as part of the development process, should we be running it again during the release?

Bundled files are not added to Git version control. If you build a dist asset locally, it will not get pushed to the remote. Therefore, the build in the remote is necessary so that the asset can be added to the Node package.

jason-capsule42 · 2024-10-01T04:22:51Z

docs/buildRelease.md

+1. CodeQL workflow is started
+1. Test and publish workflow is started with the following steps -
+    1. `npm ci`
+    1. `npm run build`


let's acknowledge the different parent build scripts.

build: run all build actions with no testing or linting
build:release: runs linters, then build then test

jason-capsule42 · 2024-10-01T04:23:35Z

docs/buildRelease.md

+    1. `npm run build`
+    1. `npm run build:test`
+        1. linters
+        1. unit tests


We should update the test scripts so that they run on the compiled/bundled component JS file so that we are testing what the end user actually gets.

jason-capsule42 · 2024-10-01T04:24:41Z

docs/buildRelease.md

+1. Test and publish workflow is started with the following steps -
+    1. `npm ci`
+    1. `npm run build`
+    1. `npm run build:test`


Do we really need this? I think the only time we need it would be part of build:release.

On principle, I don't think we should be creating wrapper scripts when they only get used once.

jason-capsule42 · 2024-10-01T04:30:12Z

docs/buildRelease.md

+            1. `build:api` 
+            1. `build:docs` 
+            1. `bundler` 
+            1. `postinstall`


The post install script literally just executes a log statement saying "Welcome to Auro" in a fancy way. We should look at just using the new Auro Library logger to present this message.

FWIW - I think we should look at adding timestopped entries into a .log file that is in the .gitignore file so that we can have better debugging on the scripts we run.

jason-capsule42 · 2024-10-01T04:31:06Z

docs/buildRelease.md

+
+1. git clone a repository
+1. Run `nvm use 20` && `npm install` (nvm step optional)
+    1. As a post-install hook, git-hook tool husky installs scripts to the .git directory. More on this in the commit section!


What is this part you are referring to here @DukeFerdinand ?

jason-capsule42 · 2024-10-01T04:32:42Z

docs/buildRelease.md

+    1. As a post-install hook, git-hook tool husky installs scripts to the .git directory. More on this in the commit section!
+1. Checkout a new feature branch off main (some branches still use master)
+1. Run `npm run build` - this is a macro to build sass files and generate TypeScript declarations
+    1. This is inconsistent? Some have `build:version` and some do not


Only components that are dependent on other auro components need build:version. But I think all components should have this as part of the build process and we should make that build:version script dynamic and able to be configured from one repo to the next, or smart enough to auto figure out what auro-components the repo is dependent on.

jason-capsule42 · 2024-10-01T04:33:58Z

docs/buildRelease.md

+1. Checkout a new feature branch off main (some branches still use master)
+1. Run `npm run build` - this is a macro to build sass files and generate TypeScript declarations
+    1. This is inconsistent? Some have `build:version` and some do not
+1. Run `npm run build:docs` to bootstrap markdown files from their static HTML


For simplicity, build:docs should be part of the build script as well as something that all components run as part of the dev watch.

jason-capsule42 · 2024-10-01T04:39:46Z

docs/buildRelease.md

+**When done working on a feature, or otherwise running git commit:**
+
+1. A commit message linter will run (commit lint)
+    1. A precommit hook runs preCommit test linters postinstall


I am not convinced that all of these are needed as part of commit lint work flow.

precommit just logs out the definition of done, which is fine.

The test and linters all get run as part of the PR actions which seem like a better place.

Any why run postinstall again? That is just the "welcome to auro" message logging.

jason-capsule42 · 2024-10-01T04:43:39Z

docs/buildRelease.md

+
+**Once code is merged into main**
+
+1. CodeQL workflow is started again


How is this actually triggered? Do we need to do it again?

https://github.com/AlaskaAirlines/WC-Generator/blob/master/template/.github/workflows/codeql.yml

jason-capsule42 · 2024-10-01T21:51:44Z

We need to address that the constant beta releases for any push is causing a semantic release issue when we try and merge beta back into main since the last commit on beta is always a "chore" release.

jason-capsule42 requested a review from a team as a code owner October 1, 2024 03:57

jason-capsule42 assigned DukeFerdinand Oct 1, 2024

jason-capsule42 linked an issue Oct 1, 2024 that may be closed by this pull request

Refine Build/Release process for all components #571

Open

2 tasks

sourcery-ai bot reviewed Oct 1, 2024

View reviewed changes

jason-capsule42 force-pushed the buildReleaseProcess branch from f5f7aad to d6ca5cd Compare October 1, 2024 04:06

jason-capsule42 commented Oct 1, 2024

View reviewed changes

docs: build and release process overview

a39d22a

jason-capsule42 force-pushed the buildReleaseProcess branch from d6ca5cd to a39d22a Compare October 1, 2024 04:13

jason-capsule42 commented Oct 1, 2024

View reviewed changes

jason-capsule42 marked this pull request as draft October 3, 2024 05:43

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

docs: build and release process overview #572

docs: build and release process overview #572

jason-capsule42 commented Oct 1, 2024 •

edited by sourcery-ai bot

Loading

sourcery-ai bot commented Oct 1, 2024 •

edited

Loading

Interacting with Sourcery

Customizing Your Experience

Getting Help

sourcery-ai bot left a comment

jason-capsule42 Oct 1, 2024

blackfalcon Oct 1, 2024

jason-capsule42 Oct 1, 2024

jason-capsule42 Oct 1, 2024

jason-capsule42 Oct 1, 2024

jason-capsule42 Oct 1, 2024

jason-capsule42 Oct 1, 2024

jason-capsule42 Oct 1, 2024

jason-capsule42 Oct 1, 2024

jason-capsule42 Oct 1, 2024

jason-capsule42 Oct 1, 2024

blackfalcon Oct 1, 2024

jason-capsule42 commented Oct 1, 2024


		Once code is merged into main

		1. CodeQL workflow is started again

docs: build and release process overview #572

Are you sure you want to change the base?

docs: build and release process overview #572

Conversation

jason-capsule42 commented Oct 1, 2024 • edited by sourcery-ai bot Loading

Alaska Airlines Pull Request

Summary:

Type of change:

Checklist:

Summary by Sourcery

sourcery-ai bot commented Oct 1, 2024 • edited Loading

Reviewer's Guide by Sourcery

Sequence Diagram

File-Level Changes

Interacting with Sourcery

Customizing Your Experience

Getting Help

sourcery-ai bot left a comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

jason-capsule42 commented Oct 1, 2024

jason-capsule42 commented Oct 1, 2024 •

edited by sourcery-ai bot

Loading

sourcery-ai bot commented Oct 1, 2024 •

edited

Loading