Contributor dashboard

Step 1 · Create a GitHub account

Do this:

If you don't have one, sign up at github.com/signup. A free account is all you need. Pick a username you're happy to have attached to your research — it becomes part of every contribution's provenance record (who gathered it, where, and when).

What you'll see: after signing up and verifying your email, you land on your GitHub home page. That's it — you're ready for step 2.

Step 2 · Register as a contributor (one time only)

Do this:

Open a New Contributor Registration issue and fill out the form — it asks about your organization and research focus. An "issue" is just a public message thread on the repository; the form does the structuring for you.

What you'll see: a maintainer reviews your registration and replies on the issue with your contributor slug — the short name (like uhm-wrrc) that names your folder in the commons. You only register once, no matter how many datasets you contribute.

Step 3 · Fork the repository

Do this:

Go to the repository page and click the Fork button at the top-right. A fork is your own personal copy of the whole repository — you can edit it freely, and nothing in the original is affected until you explicitly ask to share your changes (step 6).

What you'll see: GitHub creates a copy at github.com/YOUR-USERNAME/mokulearner-research and takes you there. Notice the "forked from Aina-Design-Corp/mokulearner-research" note under the title — that's how you know you're in your own safe copy.

Step 4 · Create your folder and metadata file

Do this:

In your fork, open the contributions/ folder, then click Add file → Create new file. In the filename box, type the full path: your-slug/dataset-slug/metadata.json — replace your-slug with your registered contributor slug and dataset-slug with a short descriptive name (e.g. koolaupoko-soil-survey-2025). GitHub creates the folders automatically each time you type a /.

In the large text box, paste the metadata template and fill in each field — title, contribution type, topics, license, quality level, and your data file's column schema. Then scroll down and click Commit changes (a "commit" is a saved snapshot with a note — GitHub's version of "save with history").

What you'll see: your new file listed inside the folders you just named, with your commit message next to it.

Step 5 · Upload your data file

Do this:

Still in your fork, navigate to contributions/your-slug/dataset-slug/ and click Add file → Upload files. Drag and drop (or browse for) your CSV or GeoJSON data file, then click Commit changes.

What you'll see: your dataset folder now holds two things — metadata.json and your data file — sitting side by side. That pair is a complete contribution.

Step 6 · Open a pull request

Do this:

Go back to the original repository at github.com/Aina-Design-Corp/mokulearner-research. GitHub shows a yellow banner noting your fork has new commits — click "Compare & pull request". A pull request (PR) is how you propose your changes for review: "here's my dataset, please take a look."

Fill in the PR form — contributor slug, dataset title, topics, record count, quality level, moku districts covered — check off the checklist, and click "Create pull request".

What you'll see: a new PR page with its own number and a conversation thread. This page is where everything about your contribution happens from now on.

Step 7 · Automated validation

Do this: nothing — just watch.

The moment your PR opens, GitHub Actions automatically checks your metadata.json and data file. Within a minute or two you'll see a green checkmark (passed) or a red X (errors found) near the bottom of the PR page. If there are errors, the check posts a comment explaining exactly what to fix.

To fix an error: go to your fork, open the file, click the pencil icon to edit, make the correction, and commit. The PR updates by itself and validation re-runs — you never need to close and re-open it.

What you'll see: the checks section flips to green once everything validates. Preliminary data is welcome — validation checks structure, not scientific perfection.

Step 8 · Review and merge

Do this: respond to any feedback.

A community maintainer reviews your contribution and either approves it or leaves comments in the PR conversation — an ordinary back-and-forth, right on the page. Once approved and merged, your dataset is part of the commons: version-controlled, provenance intact, and headed for the shared Mokunet map where it becomes comparable with research from every other moku.

What you'll see: the PR turns purple ("Merged"). To add records later, update your data file in your fork and open a new PR — existing records stay, new ones are added. Questions along the way? Open a discussion.