Contributing to the Atlas Playbook

This guide covers how to modify, test, and build Atlas. Before contributing, read the Contribution Guidelines.

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.

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:

• 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

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.

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

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

We recommend:

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

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

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
  • Helpful in diagnosing GitHub Issues

That’s it!

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