#ci #template #git #repository #continuous-integration #native #build

bin+lib automataci

Solid Foundation for Kickstarting Your Software Development

1 stable release

1.7.0 Oct 30, 2023

#225 in Template engine

Apache-2.0

15KB

AutomataCI

AutomataCI

This is a template git repository equipped with a native built-in semi-autonomous CI tool known as AutomataCI. It allows one to run a full-force CI jobs without solely relying on any 3rd-party service providers which makes the project extremely vulenrable to supply chain threat at least starting from year 2021-2023 era.

Why It Matters

Some good business reasons why using AutomataCI:

  1. Starts off with a solid & tested foundation - All the templates and CI jobs are tested and have default configured for immediate software development.
  2. Avoid being threatend by malicious suppliers - CI it's a nerve system for your product; handle it in-house and natively rather than leaving it nakedly vulnerable for any kind 3rd-party extortions.
  3. Steadily improvable - AutomataCI itself are designed to be adaptive to market changes, self-improvable, and cater to common use cases.
  4. Simple and scalable - Only uses POSIX shell and PowerShell so it works natively without much external installation.

Supported Technologies

Deployable Distributions

3rd-Party CI Integrations

AutomataCI works seamlessly out of the box by integration with:

  1. GitHub Actions
  2. GitLab CI (COMING SOON)

Documentations & Specifications

Check out the PDF file inside automataCI/docs/AutomataCI-Engineering-Specification.pdf.

It's regularly updated from time-to-time between each releases.

How To Use AutomataCI

The entire Git repository is a actually a template repository. Hence, you would either have to git clone it or download a copy of the latest source codes from the Release section. Then, execute the following steps to make sure everything is correct.

Refresh The Git Hooks

Once unpacked, you will need to refresh the git hooks by deleting the hidden .git directory at the root of the repository and then git init again. A POSIX Shell command looks as follow:

$ rm -rf .git
$ git init --initial-branch=main
$ git remote add origin <YOUR REMOTE URL>

Update Software License

By default, the presented product license (LICENSE.txt) is using the AutomataCI license. The goal is to change and update it matching to your product license.

You should also update all files inside src/licenses matching your own project. The src/licenses/LICENSE-EN.odt file is a LibreOffice Writer file. Hence, you're free to use other document generator product as long as it can produce src/licenses/LICENSE-EN.pdf for later packaging distribution use.

By default, the presented icons and banners are of AutomataCI inside src/icons/ directory generated from the materials in src/icons/principle-canvas using Inkscape design software. You're free to use other design software as long as it can generate the required output artifacts.

Once you're done designing your product brand in src/icons/principle-canvas directory, please generate an optimized and usable graphic artifacts as follow:

  1. src/icons/icon.svg - generic and widely-compatible icon file used everywhere.
  2. src/icons/icon-48x48.png - PNG 48x48 icon file used in Linux system's icon and shortcuts.
  3. src/icons/icon-128x128.png - PNG 48x48 icon file used in Linux system's icon and shortcuts.
  4. src/icons/icon-1200x400.svg - used in README.md or marketing promotion.

Update CODE_OF_CONDUCT.md

If required, please update CODE_OF_CONDUCT.md with your appropriate legal clauses.

Update CONFIG.toml

By default, AutomataCI is deploying its own CONFIG.toml product data. You should update it entirely matching your product.

Technological Selections

AutomataCI is capable of running multiple supported technologies in a repository. For example, you can enable Python technology by defining the PROJECT_PYTHON directory name (default is srcPYTHON) and Go technology by defining the PROJECT_GO directory name (default is srcGO) at the same time.

Choose wisely as the multiple tech feature consideration was made solely for those who wants to use dedicated tech for other purposes (e.g. SCULLY for static documents generation).

Update Selected Tech's CI Specific Job Recipes

The default source codes directory (src[TECH]) comes with their tech-specific AutomataCI job recipes inside its src[TECH]/.ci directory. Feel free to modify them matching your needs using your POSIX Shell and PowerShell knowledge.

Update All Distribution Resource files

All the data resource files in src/{docs,packages,publishers} shall be updated matching to your product needs. Their specifications are made available in the automataCI/AutomataCI-Engineering-Specification.pdf documentation.

Update GitHub Integration Configurations

While usually not required, you can update the GitHub integration files inside .github directory. Notable files are:

  1. .github/ISSUE_TEMPLATES/* - issue templates.
  2. .github/PULL_REQUEST_TEMPLATE/* - pull request template.
  3. .github/workflows/* - GitHub Actions workflow recipes.
  4. .github/FUNDING.yml - GitHub Sponsor button (Refer Spec).

Update README.md

Lastly, please update this README.md file. Currently, it's written for AutomataCI project. You can remove it and write a new one.

Clean Up Unused Source Directories

AutomataCI supplied a large number of source directories by tech. Once you had decided your tech, you may remove all the unused source directories (src[TECH]) and clean up the repository.

Git Commit Initial Setup

At this point, your repo is now ready. Feel free to git commit your initialization (assuming you're using main as primary branch):

$ git add .
$ git commit -s
... WRITE YOUR COMMIT ...
$ git push -u origin main:main
$ git switch --orphan gh-pages
$ git commit --allow-empty -m "Initial Commit"
$ git push origin gh-pages:gh-pages
$ git checkout main

Operating AutomataCI

To operate AutomataCI, simply execute the ci.cmd help section:

$ ./ci.cmd help

Please try any of the following:
        To seek commands' help 🠚        $ ./ci.cmd help
        To initialize environment 🠚     $ ./ci.cmd env
        To setup the repo for work 🠚    $ ./ci.cmd setup
        To prepare the repo 🠚           $ ./ci.cmd prepare
        To start a development 🠚        $ ./ci.cmd start
        To test the repo 🠚              $ ./ci.cmd test
        Like build but only for host 🠚  $ ./ci.cmd materialize
        To build the repo 🠚             $ ./ci.cmd build
        To notarize the builds 🠚        $ ./ci.cmd notarize
        To package the repo product 🠚   $ ./ci.cmd package
        To release the repo product 🠚   $ ./ci.cmd release
        To stop a development 🠚         $ ./ci.cmd stop
        To clean the workspace 🠚        $ ./ci.cmd clean
        To purge everything 🠚           $ ./ci.cmd purge

The CI jobs are arranged in a storyline manner from top to bottom. Feel free to execute accordingly.

To Contribute

AutomataCI cannot be made successfully without contributions from (Holloway) Chew, Kean Ho and supports from external folks. If you had been using AutomataCI and wish to contribute back, there are 2 ways to do so:

Financial

To financially support the project, please head over to Holloway's sponorship store here:

Sponsor

A small token purchase would helps a lot.

Craftmanship

If you wish to bring in codes contribution, bug report, and ideas, please feel free to refer the PDF engineering spec located in the automataCI/ directory.

License

AutomataCI is licensed under OSI compatible Apache 2.0 License

No runtime deps