Contributing to the Atlas Playbook

This guide covers modifying, testing, and building Atlas. Read the Contribution Guidelines first.

How the Playbook works

What Playbooks are

AME 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 Beta is the easy-to-use GUI for users to run Playbooks, and it uses the open-source TrustedUninstaller as its backend.

Browse the repository source code to see how Atlas is structured.

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

Development tools and resources:

• Visual Studio Code
  • The Atlas repo contains VSCode configs by default for building, syntax highlighting, and more
• Microsoft documentation
• AME documentation
• Nirsoft utilities
  • RegistryChangesView
  • ServiWin
• Sysinternals

How to build a Playbook

To test existing builds, check GitHub Actions, which builds a Playbook for each commit. Otherwise, clone the Atlas-OS/Atlas repo or your fork.

Using VSCode

1. Open VSCode, and open the cloned Atlas repo as a folder
2. Install the PowerShell extension
   • Non-Windows users must install PowerShell first
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
   • See the .vscode launch options to know what each option does
6. See your built Playbook in src\playbook in the repo

Using the build script directly

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

We use virtual machines for testing unless testing a final release on real hardware. This section explains how we set up VMs.

Virtualization software

We recommend:

• Hyper-V - Type-1 hypervisor (fastest), built into Windows
• VMWare Workstation - Type-2 hypervisor, good UI and features

Snapshotting

Snapshotting saves the current memory, disk, and settings of a VM so you can restore it later. For Atlas, test one Playbook, revert to unmodified Windows, then test another. You can also save snapshots for specific tests.

Which snapshots to make

We recommend making three initial snapshots:

• Stock Windows without Windows Updates installed
  • For testing installing Windows Updates after installing Atlas
  • To prevent updates from installing, 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
  • Helpful in diagnosing GitHub Issues

That’s it!

Your Atlas Playbook should be ready for testing. Test what you are working on thoroughly.