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!

How the Playbook works

What Playbooks are

AME Wizard Playbooks are a script-esque system structured in YAML to do various tasks, like running executables or setting Registry entries. An open-source backend runs these Playbooks on an easy user interface called AME Wizard.

Atlas is a Playbook, and alongside AME's documentation, we recommend searching around the repository's source code to get familiar with how the basic Playbook structure works and how we've structured Atlas' Playbook.

What Atlas uses internally

You can learn as you go, but consider getting some familiarity with the following if you're going to contribute to the Playbook directly:

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 your own fork for it.

  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 local-build.cmd, else use local-build.sh

How to run your built Playbooks

For testing, we primarily use virtual machine snapshotting 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 MMC interface, no tabs Dark mode, tabbed, easier
Snapshotting Very fast by default, worse UI as it's a list instead of a grid view Better 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 Enables 'Secure system,' which causes issues for some apps No incompatibilities with apps as it's not directly in the kernel
Guest Tools Annoying to work with as it's just an RDP session, low FPS Has a vGPU, 60fps viewport, good drag-and-drop support, stable
Operating Systems Hyper-V is only avaliable on Windows Avaliable on Linux and Windows

Apple-silicon Mac users

Due to not being tested frequently, we would appreciate it if you could test Atlas with Windows-on-ARM (11) 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.

What snapshots are

Snapshotting is a feature in most virtual machine software that saves the current memory, disk, and settings state 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 an older snapshot to test another Playbook once finished. Additionally, you can save a VM while 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 to test what you're working on extensively. 🥳