Add contribution guide

[smithara]

My initial thought here is:

1. Point people to the Binder link to test their submission (though even this could be skipped if I add a preview of the jupyterbook build, since all they need to do is add their .cof files)
2. Describe how to sign up for github and simply make a PR through the web interface "add files via upload"
3. Write some guidance on what they should look for in the test figures
4. Write instructions for local setup of the code

[ciaranbe]

Thanks for all the work on this.

My thoughts are:

1. I was hoping people would clone the repo, do their own checking on a local machine, then push their .cof files to the Github repo on a separate branch. Then we would check and merge to the protected main branch. Alternatively, they can email us the .cof files and we can use this to do our own quick checks.
2. Good idea - yes, Clemens is planning on writing something
3. I am again hoping that the modellers are expert enough to know what to look for in terms of issues, but a few helpful tips cannot go amiss
4. I am not sure what you mean by local setup - does this relate to the yml files? [I confess being unclear as to how to do this personally, so that would be helpful]

[ancklo]

On the second point above, I have been looking into ways to allow teams to upload coefficient files to the IGRF14eval repo. So far, I have found two ways:

1. Have teams fork the IGRF14eval repo so they can upload the coefficient files to their accounts. Then, ask them to create a pull request to merge their modified main branch with our main branch, which we must approve.
2. Add team members as outside collaborators to the IGRF14eval repo. But then we must ensure they have the correct permissions, which may require fine-grained adjustment. Protecting the main branch is an important first step.

But what I gather from your comment above, @smithara we can simply ask GitHub users to create a pull request without forking by using the "upload file" button on the website, which would make things much easier. But when I try to upload a file to a repo I am not a member of it says that I need push permissions. So, can it be done that way? Perhaps one needs the correct setting.

[smithara]

The process should follow option 1 - contributors make a fork and open the PR from there. So it goes like:

• Fork the repo
• Make a branch on that repo (it's helpful if we tell them to name it something like submission-bgs) and commit only their .cof files (no changes to the code - they should open an issue or a separate PR to suggest changes to the code)
• Open a PR to merge that branch (on the fork) to main here. We can then merge it right away and they are free to open another PR to update their coefficients I thought the web interface made the fork automatically when you try upload files but it looks like I was wrong. Anyway the starting point will be to make a fork using https://github.com/IAGA-VMOD/IGRF14eval/fork then add files to a branch there. It's actually a bit awkward since you have to navigate to each directory individually and add a file in 3 commits. So it might be better to avoid that and it's not a big ask for people to run git themselves. (fork on github, then git clone ... their fork, create branch, commit files, push branch, open PR)

[ancklo]

OK, this sounds good. I will go ahead and prepare a few instructions with screenshots. Maybe this can also be included in the GitHub pages later or in the repo's README.

[ancklo]

Dear all,

Here is my first attempt at writing a guide on submitting candidate models via GitHub: Instructions for submitting via GitHub.pdf

Three things came up:

1. Do we need a section about how to create a GitHub account? I could imagine this is already well explained on the GitHub website. So, it may be optional (point 0. in the guide).
2. Should we add an extra section listing the command lines for the more experienced users? Submitting through the website is straightforward but tedious, involving many clicks.
3. Should we specify in more detail the format of the pull request's title and what to include in its description section? The teams are expected to submit a description along with their candidate models. Should this be done through the pull request, too? We could also ask the teams to upload a description file in a separate directory within the repository.

[smithara]

Looks good to me. The screenshots make it quite thorough

Do we need a section about how to create a GitHub account?

I don't think so

Should we add an extra section listing the command lines for the more experienced users?

I'll add this to the README

specify in more detail the format of the pull request's title and what to include in its description

Probably not necessary. I guess any further information should come in the written description that accompanies the candidate - though I don't know whether those belong in this repository or should be sent separately.

[ciaranbe]

Thanks Clemens for the guide and Ashley making the various updates.

For the guide, do we need a couple of more sentences explaining what happens next when the pull request is sent to us? I guess the next steps are we check and approve it? Can you explain that they can run the tests themselves in Python prior to pulling if they wish?

I don't think we should add the detailed description of the candidate into the repo. It should be sent separately by email to us and we can share it online somewhere?

[ancklo]

Dear all,

I have added a section on the validation notebooks and what happens after the submission. Instructions for submitting via GitHub.pdf (version 2)

Where should we keep this file? We could add it to the repository or make an online version for the Jupyter book.

[smithara]

I guess we can add it to the repository and I'll make sure it is visible from the book