# Contributing to the Atlas package

> Build and test changes to the Atlas package.

Source: https://atlasos.net/docs/contributing/atlas-package/

This guide is for contributors who change what Atlas does to Windows. Read the [contribution guide](/docs/contributing/) first.

The [Atlas repository](https://github.com/Atlas-OS/Atlas) holds the Atlas package, Atlas Manager, and their build and test tools.

## How the Atlas package works

The Atlas package is an `.atlaspkg` file, a ZIP archive that opens with the public password `atlasos`. It holds the PowerShell scripts, data definitions and supporting files that apply Atlas to Windows. Its manifest, `atlas.json`, declares the version, the supported Windows builds, the versions it can update, the requirements and the installation choices. The repository’s [package format](https://github.com/Atlas-OS/Atlas/blob/main/docs/package-format.md) defines the archive and the manifest.

Atlas Manager prepares the PC, collects the user’s choices and then runs the package’s front door, `Executables\AtlasModules\Scripts\Entry\Install-Atlas.ps1`. The front door checks that the PC is ready, copies the package to a protected staging folder and runs the install plan as TrustedInstaller.

The front door picks one of four install modes:

| Mode    | When it runs                                                            |
| ------- | ----------------------------------------------------------------------- |
| Fresh   | Atlas isn’t installed yet.                                              |
| Upgrade | The installed Atlas version is listed in `updatableFrom`.               |
| Reapply | The installed version is the same as the package’s.                     |
| Rebase  | Windows rebuilt itself while Atlas Manager moved it to a newer release. |

On an update or reinstall, Atlas Manager asks whether to **Keep my choices** or **Choose again**. The repository’s [upgrading guide](https://github.com/Atlas-OS/Atlas/blob/main/docs/upgrading.md) explains what each mode and each answer applies.

After installation, the launchers in the Atlas folder run toggles from the same modules. The [architecture guide](https://github.com/Atlas-OS/Atlas/blob/main/docs/architecture.md) covers the install plan, identities, install state, retries and recorded choices.

## Find the relevant source

- `package/atlas.json`: the manifest, with the release version, `supportedBuilds`, `updatableFrom`, `requirements` and the installation choices.
- `package/Executables/AtlasModules`: the install framework, phases, tweaks and toggle definitions.
- `package/Executables/AtlasDesktop`: the Atlas folder’s launchers and shortcuts.
- `app`: Atlas Manager, a Rust app. See its [README](https://github.com/Atlas-OS/Atlas/blob/main/app/README.md).
- `tools` and `tests`: build tools, developer tools and automated checks.
- `docs/catalog`: generated references for every [toggle](https://github.com/Atlas-OS/Atlas/blob/main/docs/catalog/toggles.md) and install tweak.

The [contributor quick start](https://github.com/Atlas-OS/Atlas/blob/main/.github/CONTRIBUTING.md) explains how to add or change a tweak or toggle, and how to regenerate the launchers and catalog afterwards.

## Build a test package

Install **PowerShell 7** and **7-Zip or NanaZip**, then open the repository root.

On Windows:

```
.\build.cmd
```

On a Unix shell:

```
./build.sh
```

Both write `package/Atlas Test.atlaspkg` with the local test profile. That profile leaves out `supportedBuilds`, so it suits quick structure checks. Atlas Manager and the front door refuse to install it.

To build a package you can install, run a full build from PowerShell 7:

```
pwsh tools/build/Build-Package.ps1 -FileName 'Atlas Lab' -ReplaceExisting -NoExplorer
```

This writes `package/Atlas Lab.atlaspkg` with every check in place. Never distribute a package you built yourself as a release.

The build tools use PowerShell 7. The scripts in the package run on Windows PowerShell 5.1, which every supported Windows includes, so avoid syntax that only PowerShell 7 supports. The [build guide](https://github.com/Atlas-OS/Atlas/blob/main/docs/building.md) lists the build options and how to verify a built package.

## Test a built package

Use a disposable virtual machine for each supported Windows release. The [supported releases](https://github.com/Atlas-OS/Atlas/blob/main/docs/windows-release-policy.md#supported-releases) table lists them. Take a checkpoint before each test, and keep separate checkpoints for a fresh Windows installation and for each Atlas release that can update directly.

To test your full build, open your `.atlaspkg` file with the release version of Atlas Manager.

Running the front door directly

When testing, you can run `Install-Atlas.ps1` from an elevated Windows PowerShell prompt in the extracted package’s `Executables` folder. The [front door reference](https://github.com/Atlas-OS/Atlas/blob/main/docs/front-door.md) lists its parameters and exit codes. Atlas Manager remains the only way to install Atlas for users.

Check these for every change:

- The changed behaviour, its failures and a retry after a failure.
- Restarts during the **Get ready** page and after installation.
- Updates with **Keep my choices** and with **Choose again**, and a reinstall of the same version.
- The recorded choices, and **9. Troubleshooting → Check Atlas Health.cmd** after the restart.
- The installing account, another existing account and a new account.

For ISO changes, boot the created media and finish setup on the destination PC. A successful ISO build alone doesn’t prove the media works.

Follow the [testing guide](/docs/contributing/testing/) and the repository’s [testing reference](https://github.com/Atlas-OS/Atlas/blob/main/docs/testing.md), which covers the automated checks and lab VM runs. Test on real hardware as well as VMs before treating a change as verified, and [report issues](/docs/contributing/reporting/) with diagnostics and exact versions.
