Contributing to the Atlas Playbook

Use this guide to modify, build, and test the Atlas Playbook. Read the contribution guide first.

How the Playbook works

What Playbooks are

AME Playbooks bundle scripts, executables, supporting files, and YAML instructions. YAML commands called actions run executables, change Registry entries, and perform other installation work.

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

Test a built Playbook

Test development builds in a virtual machine. Test final release candidates on real hardware as well.

Virtualization software

Choose one of these virtualization tools:

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

Snapshotting

A snapshot records a VM’s memory, disk, and settings. Restore an unmodified Windows snapshot before each Playbook test so every test starts from the same state.

Which snapshots to make

Create these 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

Test your Playbook

Test the changed behavior, related features, failure paths, and reversal steps before you submit a pull request.