Create contributing file

[wenzeslaus]

...and clarify how it works with computing, freezing, rendering and stuff.

[wenzeslaus]

@cwhite911 Can you please help here?

[ecodiv]

@cwhite911 @wenzeslaus Just to check if I understand the procedure:

1. A contributor creates a fork, modifies the source (the main branch), commits the changes and creates a pull request.
2. A reviewer approves the pull request and merges it.
3. The contributor or the reviewer (I would suggest the latter) renders the website locally, updates the gh-pages branch with the updated content, commits the changes, creates a pull request and merges the changes.
4. The site is deployed automatically (?)

[petrasovaa]

@cwhite911 @wenzeslaus Just to check if I understand the procedure:

1. A contributor creates a fork, modifies the source (the main branch), commits the changes and creates a pull request.
   The same workflow as we use in main grass repo, the guide is already linked in README. A contributor creates a branch from their fork's main branch.

Ideally, at that point, their local page is built, so they commit the modifications in the freeze folder. That's what needs still to be clarified. See how this works. If they don't do that, a maintainer needs to do it and add it to the PR. Alternatively, we set the CI to do it, but my worry is this will trigger code execution (unless explicitly forbidden) and I don't think we want that. @cwhite911 any opinion on this?

2. A reviewer approves the pull request and merges it.
3. The contributor or the reviewer (I would suggest the latter) renders the website locally, updates the gh-pages branch with the updated content, commits the changes, creates a pull request and merges the changes.

this step needs to go before step 2

4. The site is deployed automatically (?)

Yes

[echoix]

Alternatively, we set the CI to do it, but my worry is this will trigger code execution (unless explicitly forbidden) and I don't think we want that. @cwhite911 any opinion on this?

If CI commits changes, especially on forks, the new commit will not trigger workflow runs.

Does only the deployment job (once merged) is enough to ship the built site to be served?

[echoix]

The contributor or the reviewer (I would suggest the latter) renders the website locally, updates the gh-pages branch with the updated content, commits the changes, creates a pull request and merges the changes.

The gh-pages approach was deprecated/removed some time ago. It works with GitHub actions and an artifact.

https://docs.github.com/en/pages/getting-started-with-github-pages/configuring-a-publishing-source-for-your-github-pages-site#creating-a-custom-github-actions-workflow-to-publish-your-site

https://github.blog/changelog/2024-07-08-pages-legacy-worker-sunset/

[cwhite911]

The current method works and is how Quarto has it documented, but I'll open a PR that uses the new method.

[echoix]

The current method works and is how Quarto has it documented, but I'll open a PR that uses the new method.

As long as the artifact to upload isn't too big, it goes well.
Under 1GB is fine. It needs to finish under 10 minutes. It cannot be bigger than 10GB. See
https://github.com/actions/upload-pages-artifact?tab=readme-ov-file#artifact-validation