Build and deployment documentation #280

ccarouge · 2025-11-21T05:57:40Z

1. Summary:

Added documentation about the building and deployment process for ACCESS-ESM1.6

2. Issues Addressed:

Fixes Build and deployment documentation #279

3. Dependencies (e.g. on payu, or model)

This change requires changes to (note pull request(s) where relevant):

workflow manager (payu):
model deployment (ACCESS-ESM1.6):
model component or library dependency:
input workflow:

4. Ad-hoc Testing

What ad-hoc testing was done? How are you convinced this change is correct (plots are good)?

Documentation only. No testing done. Relying on build preview in PR to correct formatting.

5. CI Testing

!test repro has been run
N/A: documentation only

6. Reproducibility

Is this reproducible with the previous commit? (If not, why not?)

Yes
No - !test repro commit has been run.

8. Manifests

Have you changed the executable, the input files and/or the restart files?

Yes
No

If yes, have you updated the manifests?

Yes
No

To update the manifests, run payu setup (in a cloned copy of your feature branch) with reproducibility tests turned off:

manifest:
  reproduce:
    exe: false
    input: false
    restart: false
runlog:
  enable: false

Then commit the newly created manifest files (under manifests/) only to the branch for this PR.

7. Documentation

Is the documentation updated?

Yes
N/A

9. Merge Strategy

Merge commit
Rebase and merge
Squash

github-actions · 2025-11-21T05:58:01Z

PR Preview
🚀 Preview of PR head commit `e13f6df` deployed to https://access-nri.github.io/access-esm1.6-configs/pr-previews/280
2026-02-09 13:22 AEDT
Preview generated through the Deploy to GitHub Pages workflow run 21810179954.

ccarouge · 2025-11-21T06:02:11Z

@atteggiani The config docs for ESM1.6 fail to deploy with the preview. Does it need all the PR previews to work in order to deploy? I'm happy to go and fix PR 252, just making sure that should solve the problem before investing time.

atteggiani · 2025-11-21T06:15:58Z

@atteggiani The config docs for ESM1.6 fail to deploy with the preview. Does it need all the PR previews to work in order to deploy? I'm happy to go and fix PR 252, just making sure that should solve the problem before investing time.

Yes it needs all PR previews to work, unfortunately.
If the fix takes time, you might try writing a line with !no-pr-preview in the body of the PR (PR #252 in this case). It should not trigger that PR preview. I haven't tested this properly due to RTD changes so it might not work, but it's worth a try.
It needs to be the first line of the PR body.

Then you would need to re-trigger this PR. You cannot simply retrigger the build manually, so you'll have to add a new commit or amend (no edits) and force push the latest one.

chrisb13 · 2025-11-23T21:59:49Z

Thanks @ccarouge, fwiw, you might find some of this material helpful:

ccarouge · 2025-11-24T00:51:38Z

PR #252 was fixed and the preview workflow ran from #252 has now created a preview (dismiss the failed build in this PR).

@chrisb13 I'll have a look at the links you shared.

chrisb13 · 2025-11-24T00:57:49Z

@chrisb13 I'll have a look at the links you shared.

Sure thing, @anton-seaice might be a helpful person to canvas too.

Added information on required repositories and building methods for ACCESS-ESM1.6.

chrisb13 · 2025-11-24T01:27:38Z

documentation/docs/pages/infrastructure/Building.md

-If you need to modify the source code for ACCESS-ESM1.6, you will need to use the Spack infrastructure to create your own build. There are two ways to do so (on GitHub or locally) both with benefits and limitations.
+In order to build your own version of ACCESS-ESM1.6, you will need read access to the following repositories: 
+
+- https://github.com/ACCESS-NRI/cice5


Suggested change

- https://github.com/ACCESS-NRI/cice5

- [github.com/ACCESS-NRI/cice5](https://github.com/ACCESS-NRI/cice5)

And so on for the other links...

Done. But I have completely redesigned the build page.

documentation/docs/pages/infrastructure/Building.md

aidanheerdegen

A couple of comments, but otherwise seems good, thanks.

documentation/docs/pages/infrastructure/Building.md

…higher up in mkdocs.yml Got tired of having to scroll down or search for the nav entry when it's the bit we modify the most.

ccarouge · 2026-01-20T00:32:27Z

@anton-seaice Could you review this, please? I will be away so if you can review for 2nd Feb that would be great.

…ent-documentation

anton-seaice

Sorry a bit of a chaotic review, I can have another look as needed

anton-seaice · 2026-01-20T02:54:51Z

documentation/docs/pages/infrastructure/Building.md

+
+## Software structure
+
+ACCESS-ESM1.6 being a Earth System model, it is constituted of several model components, each residing in its own repository on GitHub. In addition, some model components need other utilities at compilation time that are stored in separate repositories. This results in a complex software structure involving a large number of repositories:


Suggested change

ACCESS-ESM1.6 being a Earth System model, it is constituted of several model components, each residing in its own repository on GitHub. In addition, some model components need other utilities at compilation time that are stored in separate repositories. This results in a complex software structure involving a large number of repositories:

ACCESS-ESM1.6 being a Earth System model, it is constituted of several model components, each residing in its own repository on GitHub. In addition, some model components need other utilities at compilation time that are stored in separate repositories. This results in a complex software structure involving a number of repositories, including:

anton-seaice · 2026-01-20T02:57:24Z

documentation/docs/pages/infrastructure/Building.md

+
+## Building ACCESS-ESM1.6 using the deployment infrastructure
+
+This is the recommended method to build ad-hoc versions of ACCESS-ESM1.6 because it does not require users to have access to all the repositories, it handles the build automatically and it provides traceability and shareability of the deployment.


It needs an introduction sentence

e.g. It is possible to:

semi-automatically build ACCESS-ESM1.6 using github actions to trigger a build

and make that available to build on gadi.

this is good because it requires much less setup than using spack directly.

anton-seaice · 2026-01-20T02:59:07Z

documentation/docs/pages/infrastructure/Building.md

+# Build infrastructure
+
+Most users of ACCESS-ESM1.6 will not need to build the model. Released versions of the model are deployed by ACCESS-NRI to Gadi and available to users. Check the [Deployment page](/documentation/docs/pages/infrastructure/Deployment.md) to learn about available deployments. If you require your own build of the model, typically because you need to modify one or several model components, you will find the required information on this Builing page.
+


Do we need to define release and deploy, we use them both, slightly interchangeably

anton-seaice · 2026-01-20T03:00:17Z

documentation/mkdocs.yml

+        - Deployment:            pages/infrastructure/Deployment.md
+        - Building:              pages/infrastructure/Building.md
+        - Git practices:         pages/infrastructure/Git-practices.md
+


why did this section get moved ?

anton-seaice · 2026-01-20T03:03:05Z

documentation/docs/pages/infrastructure/Building.md

+
+## Local build of ACCESS-ESM1.6
+
+The Spack infrastructure allows you to create your own local build on _Gadi_ for ACCESS-ESM1.6. Once setup, this might be faster than using the deployment infrastructure, especially when you want a lot of small incremental builds during development.


Suggested change

The Spack infrastructure allows you to create your own local build on _Gadi_ for ACCESS-ESM1.6. Once setup, this might be faster than using the deployment infrastructure, especially when you want a lot of small incremental builds during development.

The Spack infrastructure allows you to create your own local build on _Gadi_ for ACCESS-ESM1.6. Once setup, this is faster than using the deployment infrastructure, especially when writing new code.

anton-seaice · 2026-01-20T03:09:42Z

documentation/docs/pages/infrastructure/Deployment.md

+
+There are development releases (identified with a `dev_` prefix to the date tag) and full releases (identified with only a date tag). We recommend new users start with the newest full release (i.e., with the most recent date tag). 
+
+These builds are optimised for the Sapphire-Rapid hardware from Intel (i.e., the *normalsr* queue), and may not run on Cascade-Lake (i.e., the *normal* queue) or older hardware.


I'm pretty confident it would run fine on normal. I can't see any HW specific optimisation going on

anton-seaice · 2026-01-20T03:42:01Z

documentation/docs/pages/infrastructure/Deployment.md

@@ -0,0 +1,29 @@
+# Deployment
+
+All released versions of ACCESS-ESM1.6 come with a pre-deployed build on _Gadi_. Deployed builds are stored under the project `vk83` (hence requiring [membership to this project](https://my.nci.org.au/mancini/project/vk83/join) for access). You can see all deployed builds via:


Mostly the words a "release version" would refer to a configuration, not a model exe

I think the point here is - release configurations use a certain deployment of the model code. Mostly users wouldn't mess with that.

Up to date configs will use the latest deployment, the older ones are kept for folks who are running experiments based on older configurations

anton-seaice · 2026-01-20T03:43:01Z

documentation/docs/pages/infrastructure/Deployment.md

@@ -0,0 +1,29 @@
+# Deployment
+
+All released versions of ACCESS-ESM1.6 come with a pre-deployed build on _Gadi_. Deployed builds are stored under the project `vk83` (hence requiring [membership to this project](https://my.nci.org.au/mancini/project/vk83/join) for access). You can see all deployed builds via:


under the project `vk83` (hence requiring [membership to this project](https://my.nci.org.au/mancini/project/vk83/join) for access).

this project membership is surely self evident by this point, its where payu is available from

anton-seaice · 2026-01-20T03:43:30Z

documentation/docs/pages/infrastructure/Deployment.md

+module avail access-esm1p6
+```
+
+There are development releases (identified with a `dev_` prefix to the date tag) and full releases (identified with only a date tag). We recommend new users start with the newest full release (i.e., with the most recent date tag). 


This isn't really a page for new users. What we actually recommend is that new users use a released configuration

anton-seaice · 2026-01-20T03:48:47Z

documentation/docs/pages/infrastructure/Building.md

@@ -0,0 +1,44 @@
+# Build infrastructure
+
+Most users of ACCESS-ESM1.6 will not need to build the model. Released versions of the model are deployed by ACCESS-NRI to Gadi and available to users. Check the [Deployment page](/documentation/docs/pages/infrastructure/Deployment.md) to learn about available deployments. If you require your own build of the model, typically because you need to modify one or several model components, you will find the required information on this Builing page.


The link to Deployment page doesn't work , this might be correct

Suggested change

Most users of ACCESS-ESM1.6 will not need to build the model. Released versions of the model are deployed by ACCESS-NRI to Gadi and available to users. Check the [Deployment page](/documentation/docs/pages/infrastructure/Deployment.md) to learn about available deployments. If you require your own build of the model, typically because you need to modify one or several model components, you will find the required information on this Builing page.

Most users of ACCESS-ESM1.6 will not need to build the model. Released versions of the model are deployed by ACCESS-NRI to Gadi and available to users. Check the [Deployment page](infrastructure/Deployment.md) to learn about available deployments. If you require your own build of the model, typically because you need to modify one or several model components, you will find the required information on this Builing page.

Build and deployment first draft

328a43f

ccarouge linked an issue Nov 21, 2025 that may be closed by this pull request

Build and deployment documentation #279

Open

Minor updates

a4813b8

Added information on required repositories and building methods for ACCESS-ESM1.6.

chrisb13 reviewed Nov 24, 2025

View reviewed changes

ccarouge added 3 commits December 18, 2025 12:35

(#101) - Clarify the prerequisites and the recommended build workflow

61c1cb6

(#279) - Revisiting the page completely.

7634b49

(#279) - updates after reading the rendered version.

5941467

ccarouge requested a review from anton-seaice December 18, 2025 05:32

ccarouge added 2 commits January 15, 2026 12:32

(#279) - Add information on existing deployments

d8ccbec

(#279) - Reorganise info between Building and Deployment pages.

28c0bcc

ccarouge commented Jan 15, 2026

View reviewed changes

documentation/docs/pages/infrastructure/Building.md Show resolved Hide resolved

aidanheerdegen previously approved these changes Jan 19, 2026

View reviewed changes

documentation/docs/pages/infrastructure/Building.md Outdated Show resolved Hide resolved

documentation/docs/pages/infrastructure/Building.md Outdated Show resolved Hide resolved

(#279) - Integrated Aidan's feedback

a074064

ccarouge dismissed aidanheerdegen’s stale review via a074064 January 19, 2026 23:57

ccarouge added 2 commits January 20, 2026 11:06

(#279) - add deployment page to navigation and move navigation entry …

0e39f82

…higher up in mkdocs.yml Got tired of having to scroll down or search for the nav entry when it's the bit we modify the most.

(#279) - Re-read

7347004

Merge remote-tracking branch 'origin/main' into 279-build-and-deploym…

e13f6df

…ent-documentation

anton-seaice reviewed Jan 20, 2026

View reviewed changes

ccarouge mentioned this pull request Feb 6, 2026

Configuration documentation needs for a release #371

Open

	- https://github.com/ACCESS-NRI/cice5
	- [github.com/ACCESS-NRI/cice5](https://github.com/ACCESS-NRI/cice5)


		## Software structure

		ACCESS-ESM1.6 being a Earth System model, it is constituted of several model components, each residing in its own repository on GitHub. In addition, some model components need other utilities at compilation time that are stored in separate repositories. This results in a complex software structure involving a large number of repositories:


		## Building ACCESS-ESM1.6 using the deployment infrastructure

		This is the recommended method to build ad-hoc versions of ACCESS-ESM1.6 because it does not require users to have access to all the repositories, it handles the build automatically and it provides traceability and shareability of the deployment.

		# Build infrastructure

		Most users of ACCESS-ESM1.6 will not need to build the model. Released versions of the model are deployed by ACCESS-NRI to Gadi and available to users. Check the [Deployment page](/documentation/docs/pages/infrastructure/Deployment.md) to learn about available deployments. If you require your own build of the model, typically because you need to modify one or several model components, you will find the required information on this Builing page.


		## Local build of ACCESS-ESM1.6

		The Spack infrastructure allows you to create your own local build on _Gadi_ for ACCESS-ESM1.6. Once setup, this might be faster than using the deployment infrastructure, especially when you want a lot of small incremental builds during development.


		There are development releases (identified with a `dev_` prefix to the date tag) and full releases (identified with only a date tag). We recommend new users start with the newest full release (i.e., with the most recent date tag).

		These builds are optimised for the Sapphire-Rapid hardware from Intel (i.e., the normalsr queue), and may not run on Cascade-Lake (i.e., the normal queue) or older hardware.

		@@ -0,0 +1,29 @@
		# Deployment

		All released versions of ACCESS-ESM1.6 come with a pre-deployed build on _Gadi_. Deployed builds are stored under the project `vk83` (hence requiring [membership to this project](https://my.nci.org.au/mancini/project/vk83/join) for access). You can see all deployed builds via:

		@@ -0,0 +1,44 @@
		# Build infrastructure

		Most users of ACCESS-ESM1.6 will not need to build the model. Released versions of the model are deployed by ACCESS-NRI to Gadi and available to users. Check the [Deployment page](/documentation/docs/pages/infrastructure/Deployment.md) to learn about available deployments. If you require your own build of the model, typically because you need to modify one or several model components, you will find the required information on this Builing page.

Build and deployment documentation #280

Are you sure you want to change the base?

Build and deployment documentation #280

Uh oh!

Conversation

ccarouge commented Nov 21, 2025

Uh oh!

github-actions bot commented Nov 21, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

ccarouge commented Nov 21, 2025

Uh oh!

atteggiani commented Nov 21, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

chrisb13 commented Nov 23, 2025

Uh oh!

ccarouge commented Nov 24, 2025

Uh oh!

chrisb13 commented Nov 24, 2025

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

aidanheerdegen left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

ccarouge commented Jan 20, 2026

Uh oh!

anton-seaice left a comment

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

5 participants

github-actions bot commented Nov 21, 2025 •

edited

Loading

atteggiani commented Nov 21, 2025 •

edited

Loading