Skip to content

Commit 668203b

Browse files
PathoschildPathoschild
committed
update technical docs for build pipeline
1 parent a12950b commit 668203b

File tree

1 file changed

+77
-72
lines changed

1 file changed

+77
-72
lines changed

‎docs/technical/smapi.md‎

Lines changed: 77 additions & 72 deletions
Original file line numberDiff line numberDiff line change
@@ -14,9 +14,11 @@ This document is about SMAPI itself; see also [mod build package](mod-package.md
1414
* [Compile from source code](#compile-from-source-code)
1515
* [Main project](#main-project)
1616
* [Custom Harmony build](#custom-harmony-build)
17+
* [Version format](#version-format)
1718
* [Prepare a release](#prepare-a-release)
18-
* [On any platform](#on-any-platform)
19-
* [On Windows](#on-windows)
19+
* [Automated build pipeline](#automated-build-pipeline)
20+
* [Manual release on any platform](#manual-release-on-any-platform)
21+
* [Manual release On Windows](#manual-release-on-windows)
2022
* [Release notes](#release-notes)
2123

2224
## Customisation
@@ -67,6 +69,15 @@ flag | purpose
6769
---- | -------
6870
`SMAPI_FOR_WINDOWS` | Whether SMAPI is being compiled for Windows; if not set, the code assumes Linux/macOS. Set automatically in `common.targets`.
6971

72+
## Version format
73+
SMAPI uses [semantic versioning](https://semver.org). Typical format:
74+
75+
build type | format | example
76+
:--------- | :----------------------- | :------
77+
dev build | `<version>-alpha.<date>` | `4.0.0-alpha.20251230`
78+
prerelease | `<version>-beta.<date>` | `4.0.0-beta.20251230`
79+
release | `<version>` | `4.0.0`
80+
7081
## Compile from source code
7182
### Main project
7283
Using an official SMAPI release is recommended for most users, but you can compile from source
@@ -80,89 +91,86 @@ the `SMAPI` project with debugging from Visual Studio or Rider should launch SMA
8091
debugger attached, so you can intercept errors and step through the code being executed.
8192

8293
### Custom Harmony build
83-
SMAPI uses [a custom build of Harmony 2.2.2](https://github.com/Pathoschild/Harmony#readme), which
84-
is included in the `build` folder. To use a different build, just replace `0Harmony.dll` in that
94+
SMAPI uses [a custom build of Harmony](https://github.com/Pathoschild/Harmony#readme), which is
95+
included in the `build` folder. To use a different build, just replace `0Harmony.dll` in that
8596
folder before compiling.
8697

8798
## Prepare a release
88-
### On any platform
89-
_This is the unified process that works on any platform. However, it needs a few extra steps on
90-
Windows (e.g. running Steam in WSL); see ['On Windows'](#on-windows) below for an alternative quick
91-
option._
92-
93-
#### First-time setup
99+
### Automated build pipeline
100+
SMAPI releases can be compiled automatically on GitHub. This is the recommended approach for
101+
official releases, since...
102+
- It eliminates the risk of malware on your computer infecting the release.
103+
- It creates an [attestation](https://docs.github.com/en/actions/concepts/security/artifact-attestations),
104+
so security-savvy users can verify that the release was compiled from the code on GitHub and
105+
hasn't been tampered with.
106+
- It benefits from future workflow improvements like code signing.
107+
108+
The typical process is:
109+
110+
1. Commit changes on the `develop` branch.
111+
* _Note: for an alpha version, you're done! All commits on `develop` are compiled into alpha
112+
releases. See the 'Actions' tab on GitHub._
113+
2. Set SMAPI's [version](#version-format) in `build/common.targets`, `src/SMAPI/Constants.cs`, and
114+
each mod's `manifest.json`.
115+
* _You can run `pwsh build/scripts/set-smapi-version.ps1 VERSION_HERE` to do it automatically.
116+
On Linux/macOS, you'll need to [install PowerShell](https://learn.microsoft.com/en-us/powershell/scripting/install/install-powershell)._
117+
3. Update the [release notes](../release-notes.md).
118+
4. Commit.
119+
5. Merge `develop` into `stable`.
120+
6. Tag the merge commit with the version (e.g. `5.0.0`).
121+
7. Check the 'Actions' tab on GitHub for the build, and download its artifacts when it finishes.
122+
123+
### Manual release on any platform
124+
> [!WARNING]
125+
> This lets you manually prepare a release, which is fine for personal use. However, official
126+
> releases should use the [automated build pipeline](#automated-build-pipeline) instead.
127+
128+
> [!TIP]
129+
> This approach works on any platform, but it's a bit complicated on Windows. See also [_Manual
130+
> release on Windows_](#manual-release-on-windows) for a simpler approach.
131+
132+
First-time setup:
94133
1. On Windows only:
95134
1. [Install Windows Subsystem for Linux (WSL)](https://docs.microsoft.com/en-us/windows/wsl/install).
96135
2. Follow the rest of the instructions inside WSL.
97-
2. Install the required software:
98-
1. Install...
99-
- [.NET 6 SDK](https://docs.microsoft.com/en-us/dotnet/core/install/linux-ubuntu) (run
100-
`lsb_release -a` if you need the Ubuntu version number);
101-
- [PowerShell](https://learn.microsoft.com/en-us/powershell/scripting/install/install-powershell-on-linux);
102-
- and [Steam](https://linuxconfig.org/how-to-install-steam-on-ubuntu-20-04-focal-fossa-linux).
103-
3. Launch `steam` and install the game like usual.
104-
4. Download and install your preferred IDE. For the [latest standalone Rider
105-
version](https://www.jetbrains.com/help/rider/Installation_guide.html#prerequisites):
106-
```sh
107-
wget "<download url here>" -O rider-install.tar.gz
108-
sudo tar -xzvf rider-install.tar.gz -C /opt
109-
ln -s "/opt/JetBrains Rider-<version>/bin/rider.sh"
110-
./rider.sh
111-
```
112-
3. Clone the SMAPI repo:
136+
2. Install...
137+
- [.NET 6 SDK](https://docs.microsoft.com/en-us/dotnet/core/install/linux-ubuntu) (run
138+
`lsb_release -a` if you need the Ubuntu version number);
139+
- [PowerShell](https://learn.microsoft.com/en-us/powershell/scripting/install/install-powershell);
140+
- and Steam (see [Linux instructions](https://linuxconfig.org/how-to-install-steam-on-ubuntu-20-04-focal-fossa-linux)).
141+
3. Launch `steam` and install the game like usual.
142+
4. Clone the SMAPI repo:
113143
```sh
114144
git clone https://github.com/Pathoschild/SMAPI.git
115145
```
116146

117-
### Launch the game
118-
1. Run these commands to start Steam:
119-
```sh
120-
export TERM=xterm
121-
steam
122-
```
123-
2. Launch the game through the Steam UI.
124-
125-
### Prepare the release
147+
To prepare the release:
126148
1. Run `pwsh build/scripts/prepare-install-package.sh VERSION_HERE` to create the release package in the
127-
root `bin` folder.
128-
129-
Make sure you use a [semantic version](https://semver.org). Recommended format:
130-
131-
build type | format | example
132-
:--------- | :----------------------- | :------
133-
dev build | `<version>-alpha.<date>` | `4.0.0-alpha.20251230`
134-
prerelease | `<version>-beta.<date>` | `4.0.0-beta.20251230`
135-
release | `<version>` | `4.0.0`
136-
137-
### On Windows
138-
_This is the alternative quick process for Windows only. This avoids needing Steam installed on WSL,
139-
and can be used to create Windows-only builds without using WSL at all. See ['on any platform'](#on-any-platform)
140-
above for the unified process._
141-
142-
#### First-time setup
143-
1. Set up Windows Subsystem for Linux (WSL):
144-
1. [Install WSL](https://docs.microsoft.com/en-us/windows/wsl/install).
145-
2. Run `sudo apt update` in WSL to update the package list.
146-
3. The rest of the instructions below should be run in WSL.
147-
2. Install the required software:
148-
1. Install the [.NET 5 SDK](https://dotnet.microsoft.com/download/dotnet/5.0).
149-
2. Install [Stardew Valley](https://www.stardewvalley.net/).
150-
3. Clone the SMAPI repo:
149+
root `bin` folder. Make sure you use a [semantic version](#version-format).
150+
151+
### Manual release On Windows
152+
> [!WARNING]
153+
> This lets you manually prepare a release, which is fine for personal use. However, official
154+
> releases should use the [automated build pipeline](#automated-build-pipeline) instead.
155+
156+
> [!TIP]
157+
> To prepare a Windows-only build, you can skip WSL and replace `--skip-bundle-deletion` with `--windows-only`
158+
> when calling `prepare-install-package.ps1`.
159+
160+
First-time setup:
161+
1. Install...
162+
- [Windows Subsystem for Linux (WSL)](https://docs.microsoft.com/en-us/windows/wsl/install);
163+
- [.NET 6 SDK](https://dotnet.microsoft.com/download/dotnet/5.0);
164+
- [Stardew Valley](https://www.stardewvalley.net/).
165+
2. Clone the SMAPI repo:
151166
```sh
152167
git clone https://github.com/Pathoschild/SMAPI.git
153168
```
154169

155-
### Prepare the release
170+
To prepare the release:
156171
1. Run `pwsh build/scripts/prepare-install-package.ps1 VERSION_HERE --skip-bundle-deletion` to
157-
create the release package folders in the root `bin` folder.
158-
159-
Make sure you use a [semantic version](https://semver.org). Recommended format:
160-
161-
build type | format | example
162-
:--------- | :----------------------- | :------
163-
dev build | `<version>-alpha.<date>` | `4.0.0-alpha.20251230`
164-
prerelease | `<version>-beta.<date>` | `4.0.0-beta.20251230`
165-
release | `<version>` | `4.0.0`
172+
create the release package folders in the root `bin` folder. Make sure you use a [semantic
173+
version](#version-format).
166174

167175
2. Launch WSL and run this script:
168176
```bash
@@ -173,8 +181,5 @@ above for the unified process._
173181
pwsh build/scripts/finalize-install-package.sh "$version" "$binFolder"
174182
```
175183

176-
Note: to prepare a test Windows-only build, you can pass `--windows-only` in the first step and
177-
skip the second one.
178-
179184
## Release notes
180185
See [release notes](../release-notes.md).

0 commit comments

Comments
 (0)