Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
74 changes: 71 additions & 3 deletions src/content/docs/contributing/autoupdate.mdx
Original file line number Diff line number Diff line change
Expand Up @@ -22,9 +22,8 @@ Updates are triggered every 10 minutes using <Code code={`anda updat
<Aside icon="open-book">
Actually, the [full
command](https://github.com/terrapkg/packages/blob/4767e5b9560f2986accaeb8447fbb4ea742041cf/.github/workflows/update.yml#L27-L31)
for auto-updating normal packages is: (as of 2024-08-09) ```sh
RUST_BACKTRACE=full GITHUB_TOKEN=... anda update -vv --excludes nightly=1
--excludes updbranch=1 ```
for auto-updating normal packages is: (as of 2024-08-09) ```sh RUST_BACKTRACE=full
GITHUB_TOKEN=... anda update -vv --excludes weekly=1 --excludes updbranch=1 --excludes nightly=1 --excludes nightly=2 --excludes nightly=3 --excludes nightly=4 --excludes quadridaily=1 ```
</Aside>

## Common Update Scripts
Expand Down Expand Up @@ -182,6 +181,75 @@ if rpm.changed() { // This if statement updates the "commit_date" if "ver" and/o
}
```

## Quaterdaily packages

Quaterdaily packages are updated every 6 hours using

<Code
code={`anda update --filters quaterdaily=1`}
lang="ansi"
inline
/>
. Their `anda.hcl` files should look something like this (with the `quaterdaily = 1` label):

```hcl
project pkg {
rpm {
spec = "package-name.spec"
}
labels {
quaterdaily = 1
}
}
```

Now, let's go over some common quaterdaily `update.rhai` examples.

### GitHub Commit Tracking

This is the most commonly used GitHub update script. It tracks the commit of a package hosted on GitHub.

```ts
rpm.global("commit", gh_commit("FyraLabs/subatomic")); // Grab the latest commit from GitHub, then update the globally defined RPM macro "commit"
if rpm.changed() {
rpm.release();
rpm.global("commit_date", date()); // Update the globally defined "commit_date" to the date of the commit
rpm.global("run", quaterdaily_run()); // Set the run number based on the quarter of the day
}
```

Replace `FyraLabs/subatomic` with the GitHub link, minus the `https://github.com/`.

### GitLab Commit Tracking

This is the most commonly used GitLab update script. It tracks the commit of a package hosted on GitLab.

```ts
rpm.global("commit", gitlab_commit("gitlab.com", "24306684", "main"));
if rpm.changed() {
rpm.global("commit_date", date());
rpm.global("run", quaterdaily_run());
rpm.release();
}
```

Replace `gitlab.com` with a custom GitLab link (if there is one), replace `24306684` with the GitLab Project ID, and replace `main` with the branch to track.

### Nightly Versions of a Stable Package update.rhai

If you have a nightly version of a stable package, you will need to track commits and versions of the package.
To do this, you would use an `update.rhai` like this:

```ts
rpm.global("commit", gh_commit("FyraLabs/subatomic")); // Track latest commit of package, update the globally defined RPM macro "commit"
if rpm.changed() { // This if statement updates the "commit_date" and "run" if "ver" and/or "commit" changed, so the latest commit of a package is always the latest version that gets installed by a user
rpm.release();
rpm.global("ver", gh("FyraLabs/subatomic")); // Track latest release version of package, update the globally defined RPM macro "ver"
rpm.global("commit_date", date());
rpm.global("run", quaterdaily_run());
}
```

## Per-branch auto-update scripts

Terra supports updating a package for specific branches instead of updating a package for all branches.
Expand Down
3 changes: 2 additions & 1 deletion src/content/docs/contributing/getting-started.mdx
Original file line number Diff line number Diff line change
Expand Up @@ -258,7 +258,8 @@ See the "book" (more like guide) for [Rhai].

- Create an `update.rhai` file inside the folder of your package alongside your `.spec` file.
- See references from other packages.
- You also need to add <Code code={`labels { nightly = "1" }`} lang="hcl" inline /> in `anda.hcl` for nightly packages.
- You need to add <Code code={`labels { nightly = "1" }`} lang="hcl" inline /> in `anda.hcl` for nightly packages.
- You need to add <Code code={`labels { quaterdaily = "1" }`} lang="hcl" inline /> in `anda.hcl` for quaterdaily packages.

<Aside>Remember to add semicolons in Rhai scripts! (`;`)</Aside>

Expand Down
10 changes: 7 additions & 3 deletions src/content/docs/contributing/policies.mdx
Original file line number Diff line number Diff line change
Expand Up @@ -103,8 +103,12 @@ Packages SHOULD follow one of the version formats below:
Version: %{latest_stable_version}
## (Commit tacking (nightly off version tag))
Version: %{latest_stable_version}^%{commit_date}git.%{shortcommit}
## (Commit tacking (no stable version tag))
## (Commit tracking (nightly, no stable version tag))
Version: %{unreleased_version}~%{commit_date}git.%{shortcommit}
## (Commit tracking (quaterdaily off version tag))
Version: %{latest_stable_version}^%{commit_date}^{quaterdaily_run}git.%{shortcommit}
## (Commit tracking (quaterdaily, no stable version tag))
Version: %{unreleased_version}^%{commit_date}^{quaterdaily_run}git.%{shortcommit}
```

`git` SHOULD be replaced with the correct _VCS identifier_ for **(b)** and **(c)** as listed below.
Expand All @@ -123,13 +127,13 @@ Version: %{unreleased_version}~%{commit_date}git.%{shortcommit}
| Fossil | `fsl` |
</div>

If either commit tracking option is used, you MUST also include <Code code={`labels { nightly = 1 }`} lang="hcl" inline /> in `anda.hcl` unless there is no `update.rhai`,
If either commit tracking option is used, you MUST also include <Code code={`labels { nightly = 1 }`} lang="hcl" inline /> OR <Code code={`labels { quaterdaily = 1 }`} lang="hcl" inline /> in `anda.hcl` unless there is no `update.rhai`,
as these two formats rely on the assumption that there is one <Code code={`%shortcommit`} lang={RPMSpec} inline /> for each <Code code={`%commit_date`} lang={RPMSpec} inline /> (and vice versa).

<Code code={`%{unreleased_version}`} lang={RPMSpec} inline /> refers to the expected version number for the next stable (or a more stable tag than <Code code={`nightly`} lang={RPMSpec} inline />) release,
while <Code code={`%{latest_stable_version}`} lang={RPMSpec} inline /> refers to the current latest released version number, preferably stable.

If there are stable releases but the package is build from a commit, you SHOULD append a commit to the version when there is a stable and nightly version of a package.
If there are stable releases but the package is build from a commit, you SHOULD append a commit to the version when there is a stable and nightly/quaterdaily version of a package.

If upstream does not provide a version, use the commit to `0^` instead.

Expand Down
Loading