Config repos unsearchable / broken wiki links

[aekiss]

GitHub only searches the default branch, so shifting the config content out of the main branch has made the configs unsearchable.

This has also broken a whole lot of links in the wiki (e.g. https://github.com/COSIMA/access-om3/wiki/Configurations), which were mostly GitHub search queries.

I'm not sure what to do about this. Being unable to search the branches via the UI is a real hindrance to understanding and documenting the configs.

Maybe the default branch should be something useable, e.g. 1deg_jra55do_ryf rather than just a README?

[micaeljtoliveira]

Hmm, that's quite annoying. Personally I wouldn't change the main branch. I think the reasons for leaving it empty are good ones. Also, it might be misleading to have a search that only works on one configuration, ignoring all the others.

I see two other options:

• use something else to document and search the configurations
• split the configurations into different repositories and change the existing one to include them via git submodules.

I think I favor the first option, but all have pros and cons...

[aekiss]

I think it would work quite well to set 1deg_jra55do_ryf as the default branch, and document in the README how to switch to others, and explain that only the default branch is searchable via github. I don't think this would cause any confusion, since the default branch would not be called main. The documentation in the wiki just uses one config as an example, so I'm not too worried that it would exclude others.

Re. your first dot point, did you have something in mind as a way to search/document non-default branches in the configs? It can be done offline with git grep but documentation would need a method that provides a url to source lines. I've been using searches rather than permalinks so the links won't need to be updated as we develop the configs.

re. 2nd dot point, we wanted to avoid splitting into multiple repos to make it easier to maintain multiple configs. I think this consideration more than compensates for the annoying Github limitations on searching other branches.

[micaeljtoliveira]

What about adding some config files in the main branch to fix the wiki documentation, but no config.yaml, so that it's not runnable with payu?

[anton-seaice]

It looks like you can search branches in github.dev

1. Select the branch you want on github.com, then open it in github.dev (press . on the keyboard).
2. Select the Search function in the sidebar

(ref https://stackoverflow.com/questions/31891733/searching-code-in-a-specific-github-branch)

[aekiss]

Wow, that's cool! But is it possible to see the results of a search via a url like this? I'd need that for links.
https://github.com/search?q=repo%3ACOSIMA%2Faccess-om3+MOM6&type=code

[anton-seaice]

Oh i see the problem now ... not possible in anyway I can see

[aekiss]

What about adding some config files in the main branch to fix the wiki documentation, but no config.yaml, so that it's not runnable with payu?

Unfortunately I don't think that would work. The wiki currently searches in these files (which includes config.yaml), and we'd probably want to search more as the documentation takes shape.

• config.yaml
• nuopc.runconfig
• nuopc.runseq
• MOM_input

I think having so many files (including config.yaml) in 'main' would be more confusing than just using an actual config, and more of a maintenance burden to keep it synced with the working config branch it's based on.

[micaeljtoliveira]

@aekiss I think this could still work if all the files, including the config.yaml file, are put into a subdirectory (e.g. doc). That way it would be much less likely for people to try and run it by mistake. It would also allow for more files to be included later, without cluttering the root directory.

Edit: this would still require manual update of the files. On the other hand, it would allow to list more options than those that are used in the 1deg_jra55do_ryf configuration.

[aekiss]

Ah, good idea, let's do that and see how we go.

[aekiss]

See if this PR fits the bill ACCESS-NRI/access-om3-configs#36

Still need to update links in wiki.

[aekiss]

Closing - I've added the necessary files to MOM6-CICE6/doc and fixed search links in the wiki.

We should run MOM6-CICE6/doc/update_doc.sh regularly to keep the files in MOM6-CICE6/doc up to date with the 1deg_jra55do_ryf branch (or perhaps a different branch in future).

At some point we may want to switch to basing the wiki documentation on MOM6-CICE-WW3, so this PR will facilitate that ACCESS-NRI/access-om3-wav-configs#16