Skip to content

Contributing to the Atlas Playbook

This page will cover how to modify, test, and build Atlas. If you plan to contribute, we recommend reading the Contribution Guidelines first!

Our contribution platform

Atlas uses GitHub to manage everything. Please note that our documentation does not contain instructions on how to use GitHub or Git; if you're unfamiliar with them, see the GitHub quick-start guide first.

How the Playbook works

What Playbooks are

AME Wizard Playbooks are bundles of regular scripts, executables, and other files alongside script-like AME YAML files. These YAML files have commands called actions, which can do things like running executables or setting Registry entries.

AME Wizard is the easy-to-use GUI for users to run Playbooks, and it uses the open-source TrustedUninstaller as its backend.

To start adding to Atlas, we recommend browsing our repository's source code to get familiar with how we've structured Atlas.

What Atlas uses internally

The Atlas Playbook primarily uses the following three languages:

  1. PowerShell scripting
  2. Batch scripting
  3. YAML - Yet Another Markup Language

For development tools and resources, we recommend using:

How to build a Playbook

If you want to test existing builds, consider viewing our GitHub Actions, which builds a Playbook for each commit. Otherwise, clone the Atlas-OS/Atlas repo before continuing or using your fork.

  1. Open VSCode, and open the cloned Atlas repo as a folder
  2. Install the PowerShell extension
  3. Install 7-Zip or NanaZip if not done already
    • For macOS/Linux, install 7-Zip (official or p7zip) using a package manager
  4. Optional: Install the other extensions recommended in the 'Extensions' tab
  5. Use the 'Run and Debug' options to build a Playbook
  6. See your built Playbook in src\playbook in the repo
  1. Install 7-Zip or NanaZip if not done already
    • For macOS/Linux, install 7-Zip (official or p7zip) using a package manager
  2. For macOS/Linux, install the latest PowerShell
  3. Navigate to src\playbook in the cloned Atlas repo
  4. If on Windows, run build-playbook.cmd, else use build-playbook.sh

How to run your built Playbooks

For testing, we primarily use virtual machines unless we are testing for a final release, in which case we test on real hardware.

This section will tell you how we set up virtual machines for testing.

Virtualization Software

Here's a comparison of our two recommendations:

Hyper-V VMWare Workstation
Hypervisor Type-1 hypervisor (fastest) Type-2 hypervisor (fast)
Interface List interface, native-looking Dark mode, tabbed, easier
Snapshotting Very fast by default, a simple list for the UI Good grid UI, but you should disable taking snapshots in background for speed
Ease of Installation Installation through Windows features, no external downloads It's officially free now, but you need to tediously sign-up for a Broadcom account
Compatibility Oversees the entire OS, which causes issues for some apps No incompatibilities with apps as it's not as low-level
Guest Tools Uses RDP internally, low FPS, minor artifacts, no vGPU Has a vGPU, 60fps viewport, good drag-and-drop support, stable
OS Support Only available on Windows Available on Linux and Windows

Apple-silicon Mac users

We would appreciate it if you could test Atlas with Windows 11 on-ARM using your Apple-silicon-based device. For this, consider using either:

VMWare Fusion (free with Broadcom account) Parallels (14-day trial)

Note: ARM ISOs aren't available on Microsoft's website. Instead, these apps download them for you.

Snapshotting

Snapshotting is a feature in most virtual machine software that saves the current memory, disk, and settings of a virtual machine so that you can restore it later.

Snapshots are handy for Atlas as you can test one Playbook and revert to unmodified Windows to test another Playbook once finished. Additionally, you can save a snapshot for testing something specific and return to it later.

Which snapshots to make

Setup your snapshots ready for a Playbook

It's best to make your initial snapshots already set up with AME Wizard and some essential utilities (e.g. Sysinternals) so that you can just drag-and-drop a Playbook as soon as you go to a snapshot.

We recommend making three initial snapshots:

  • Stock Windows without Windows Updates installed
    • For testing installing Windows Updates after installing Atlas
    • To ensure updates don't install, pause updates indefinitely before connecting to the internet. Un-pause them later in Windows Settings
  • Stock Windows with Windows Updates installed
    • Consider updating Windows and remaking the snapshot every so often
  • Optional: A current release Atlas snapshot if you need to test anything there

That's it!

Any Atlas Playbook should be ready to get tested now. Ensure that you extensively test what you're working on. 🥳