esm1.6 configuration documentation

[chrisb13]

Note that if the concept is to have a subdomain config, e.g. https://access-esm1.6-configs.access-hive.org.au/, then that takes some times to organise.

(fyi @AndyHoggANU, finally!)

[anton-seaice]

Thankyou for starting this.

The normal procedure is to make an issue, agree/document an approach and use the issue number in the branch name. Along those lines .. there's no information on what the scope of this change is or should be, so it's hard to confirm its been completed.

Could all the files with .un~ be removed please? I can't see what they are for. There are numerous other copy/paste errors /unused files - e.g. in assets, references.bib, the docs/index.md (as opposed to the docs/pages/index.md file)

All the ACCESS-NRI authored files should have a copyright / license statement at the top, e.g:

# Copyright 2025 ACCESS-NRI and contributors. See the top-level COPYRIGHT file for details.
# SPDX-License-Identifier: Apache-2.0

Should CSIRO be listed in the copyright statement too ?

[chrisb13]

Thanks for the feedback @anton-seaice

The normal procedure is to make an issue, agree/document an approach and use the issue number in the branch name. Along those lines .. there's no information on what the scope of this change is or should be, so it's hard to confirm its been completed.

Okay, in this instance, the need for an esm1.6 config' doc has been discussed a few times and I thought was uncontentious? The point of this PR then is just to start an empty document.

Could all the files with .un~ be removed please? I can't see what they are for. There are numerous other copy/paste errors /unused files - e.g. in assets, references.bib, the docs/index.md (as opposed to the docs/pages/index.md file)

They have been removed.

All the ACCESS-NRI authored files should have a copyright / license statement at the top, e.g:

This was based on om3 config doc that I gather didn't have those files? Feel free to add where you think it's appropriate.

Should CSIRO be listed in the copyright statement too ?

I guess they are covered under the and contributors sentence but if they wish to be listed more explicitly let's do that.

[anton-seaice]

@aidanheerdegen / @micaeljtoliveira - I am confused about how to license this. This change adds documentation for the access-esm1.6-configs, which exists in the main branch of the repo. The repo is licensed with Apache-2.0 but it says in dev-docs to use cc-by-4.0 for documentation. I suspect Apache-2.0 is fine?

I am also confused about the need for a header statement. In python files we tend/sometimes have :

# Copyright 2023 ACCESS-NRI and contributors. See the top-level COPYRIGHT file for details.
# SPDX-License-Identifier: Apache-2.0

but we don't seem to have this header in documentation or config files etc ?

[anton-seaice]

@chrisb13 - youll need to sign your commits.

Will you raise an issue to encourage people to add content ?

[chrisb13]

Will you raise an issue to encourage people to add content ?

I'm happy to, but I think it's best if we decide on the (at least temporary) hosting choice. As in, are we going to not merge this PR and then people can just commit to it? This gives PR previews at least for the interim.

Or is the preference to have it hosted somewhere first and then ask for contributions? (@atteggiani has said it's impractical to organise a subdomain before the workshop.)

[chrisb13]

@chrisb13 - youll need to sign your commits.

It's just this 2d04ea2 that's the problem right?

Update: now fixed: e978272

[anton-seaice]

Will you raise an issue to encourage people to add content ?

I'm happy to, but I think it's best if we decide on the (at least temporary) hosting choice. As in, are we going to not merge this PR and then people can just commit to it? This gives PR previews at least for the interim.

Or is the preference to have it hosted somewhere first and then ask for contributions? (@atteggiani has said it's impractical to organise a subdomain before the workshop.)

I think its fine to merge and use https://access-nri.github.io/access-esm1.6-configs/ temporarily until there is a subdomain ?

[chrisb13]

I think its fine to merge and use https://access-nri.github.io/access-esm1.6-configs/ temporarily until there is a subdomain ?

Yeah I think that's a tidy solution for the time being. If there's no objections @ACCESS-NRI/hivedocsteam ?

[chrisb13]

@anton-seaice looks like we can merge now, pending resolving your licence query / everyone ok with https://access-nri.github.io/access-esm1.6-configs/.

[atteggiani]

@anton-seaice looks like we can merge now, pending resolving your licence query / everyone ok with https://access-nri.github.io/access-esm1.6-configs/.

I would suggest not to advertise urls that will then be changed.

[chrisb13]

I think its fine to merge and use https://access-nri.github.io/access-esm1.6-configs/ temporarily until there is a subdomain ?

I think Anton and I could have been clearer. We're looking for a temporary home for dev work, so it wouldn't be "advertised" beyond the development team.

[anton-seaice]

This is a useful starting point, thanks @chrisb13

I think the license thing could be clearer, we seem a bit inconsistent in our approach, but there is a license file in the top level in the repo, so it is communicated to some extent that the docs are under an open source license

[ccarouge]

@anton-seaice @chrisb13 Can you access the preview? I can only see the landing page. "Home" takes me to "404" and "Configuration" keeps me on the landing page. Makes it hard to review the text.

[chrisb13]

Yeah, it's just a container for the moment, I think when I merge this, it'll break a few more links that I'll need to fix...

Update: actually seems to have worked!

[ccarouge]

Important, a copyright can only be held by one legal entity, so the copyright line can not read: "ACCESS-NRI, CSIRO and contributors". The acknowledgement of CSIRO and other contributors need to come differently. Can add the logos and some text on the home page. @chrisb13

[chrisb13]

Important, a copyright can only be held by one legal entity, so the copyright line can not read: "ACCESS-NRI, CSIRO and contributors". The acknowledgement of CSIRO and other contributors need to come differently. Can add the logos and some text on the home page. @chrisb13

Thanks @ccarouge, can you please make the changes you suggest.

[anton-seaice]

It is fairly common to see it in software, e.g.

Earth System Modeling Framework
Copyright (c) 2002-2025, University Corporation for Atmospheric Research,
Massachusetts Institute of Technology, Geophysical Fluid Dynamics
Laboratory, University of Michigan, National Centers for Environmental
Prediction, Los Alamos National Laboratory, Argonne National Laboratory,
NASA Goddard Space Flight Center.
Licensed under the University of Illinois-NCSA License.

https://github.com/esmf-org/esmf/blob/d442afe351a4a255f40823e2f57d4dceab18ed90/src/Infrastructure/Util/include/ESMF.h#L5-L9

although that doesn't mean its correct of course

[micaeljtoliveira]

It is fairly common to see it in software

Copyright laws are different from country to country, so what is valid in the US might not be in Australia.

Important, a copyright can only be held by one legal entity

@ccarouge Is this a special feature of Australian copyright laws? Because most other countries do allow multiple copyright holders, provided they are legal entities (which also includes individuals).

[chrisb13]

Important, a copyright can only be held by one legal entity, so the copyright line can not read: "ACCESS-NRI, CSIRO and contributors". The acknowledgement of CSIRO and other contributors need to come differently. Can add the logos and some text on the home page. @chrisb13

Thanks @ccarouge, can you please make the changes you suggest.

Just to follow up, I think we should check in with the relevant person at CSIRO before adding logos and explicit text. @ccarouge perhaps you have a contact for that? It sounds like you've been down this road before.

[ccarouge]

Or I'm misremembering what I learnt before because I don't use it much. :D
I've re-read online, and it looks like I was mistaken, sorry. One thing, though, with "and contributors", we may have to be able to provide a list of specific names, and I have no idea if GitHub handles would be judged sufficient or if we would need real names. There is a very, very small chance of this happening (only if there is a dispute around copyright) so we may not want to worry too much about it.

[chrisb13]

Okay, thanks for clarifying @ccarouge, so it sounds like you think we're okay for now?

FWIW, if we wish for people to be named explicitly in the future, I think we could use something like this.