This guide shows how to submit a new macro and update it later using only the GitHub website — no git, no command line. The rules themselves are in CONTRIBUTING.md.
- You need a free GitHub account, and you need to be signed in.
- Have your macro ready on your computer and tested in OpenSAK.
-
Get the two template files from
template/my-macro/: open each file (my-macro.luaandREADME.md) and click Download raw file (the download icon above the file). Put both in a new folder on your computer. -
Rename the folder and the
.luafile to your macro's name. Use lowercase letters, digits and hyphens only, and give both the same name:find-easy-traditionals/ ├── find-easy-traditionals.lua └── README.md -
Fill in the header at the top of the
.luafile. Every line is required:-- OpenSAK Macro -- Name: Find easy traditionals -- Author: Jane Doe -- Version: 1.0 -- Requires-API: 3 -- Description: Filters for unfound traditional caches with low difficulty. -- Permissions: none
- Author: your name or nickname — your geocaching name is fine.
- Permissions: list everything the macro can do (
write,read-files,write-files,open,run-macros). If it only reads data, writenone. - Network: add this line only if the macro contacts web sites. Give
plain host names such as
api.example.com. Geocaching HQ's sites (geocaching.com,coord.info,waymarking.com,wherigo.comand related domains) are not allowed.
-
Write the
README.md: what the macro does, how to use it, and what it needs. -
Don't include any personal data: no account names, home coordinates, log texts or databases of your own.
- Open https://github.com/OpenSAK-Org/OpenSAK-Macros.
- Click Fork (top right), then Create fork.
You now have your own copy at github.com/<your-name>/OpenSAK-Macros. You
only do this once; bookmark it.
- In your fork, open the
macrosfolder. - Click Add file → Upload files.
- Drag your whole macro folder into the upload area, not just the files inside it. GitHub keeps the folder structure.
- Check the file list: the paths must look like
macros/find-easy-traditionals/.... - Under Commit changes:
- Message: for example
Add find-easy-traditionals. - Select Create a new branch for this commit and start a pull request,
and name the branch, for example
add-find-easy-traditionals. - Click Propose changes.
- Message: for example
⚠️ The pull request must go toOpenSAK-Org/OpenSAK-Macros, not to your own fork. After "Propose changes", GitHub often opens a page that compares branches inside your fork. A pull request created there never reaches the maintainers.
The easiest way to get it right:
- Open https://github.com/OpenSAK-Org/OpenSAK-Macros (the original, not your fork).
- A yellow banner says "add-find-easy-traditionals had recent pushes". Click Compare & pull request in it. This page already points to the right place.
Or, on the page GitHub opened after "Propose changes":
- Look at the top line. If it only shows
base: main ← compare: …(no "base repository"), click the link compare across forks just above it. - Set base repository to
OpenSAK-Org/OpenSAK-Macros.
Either way, check the top line before you continue. It must say:
base repository:
OpenSAK-Org/OpenSAK-Macros· base:main← head repository:<your-name>/OpenSAK-Macros· compare:add-find-easy-traditionals
Then:
- Title: for example
New macro: Find easy traditionals. - Description: one or two sentences on what the macro does, and anything the reviewer should know. Tick the boxes in the checklist.
- Leave Allow edits by maintainers ticked.
- Click Create pull request.
At the bottom of the pull request, the checks run (about a minute).
- ✅ Green: the pull request gets the label
needs review. Wait for a maintainer. - ❌ Red: click Details next to the failed check to see why. Common
causes:
- a header line is missing
- a word in
Permissionsisn't on the allowed list - a
Networkentry isn't a plain host name - the Lua code has a syntax error
- files from more than one macro folder are in the pull request
To fix something: in your fork, switch to your branch (branch dropdown at the top left), open the file, click the ✏️ pencil, edit, and Commit changes directly to that branch. The pull request updates itself and the checks run again.
- A maintainer reviews every new macro. Answer any questions in the pull request.
- Once it's merged, the maintainer registers your GitHub account as the macro's owner. From then on your updates can be merged automatically (see Guide 2).
- Optional: click Delete branch in the pull request to tidy up.
Two macros means two pull requests. Repeat Steps 3–6 with a new branch for each.
- Open your fork (
github.com/<your-name>/OpenSAK-Macros), on branchmain. - If GitHub says "This branch is X commits behind", click Sync fork → Update branch.
This makes sure you're editing the version that is published now.
- In your fork, open
macros/<your-macro>/<your-macro>.lua. - Change it in one of two ways:
- Edit in the browser: click ✏️ (Edit this file) and make your changes or paste in the new code.
- Replace it with your local file: open the macro folder, click Add file → Upload files, and upload the file with exactly the same name. It replaces the old one.
- Raise the
Versionin the header, for example1.0→1.1. The check fails if you don't. - If you changed what the macro does, update
PermissionsandNetworktoo. - Commit changes → select Create a new branch… (for example
update-find-easy-traditionals-1.1) → Propose changes.
- Make sure you're on your new branch (branch dropdown).
- Edit
README.mdwith ✏️ and commit directly to theupdate-…branch.
Same as Guide 1, Step 4. This matters even
more for updates: after "Propose changes" in your fork, GitHub nearly always
compares branches inside your fork, without a "base repository" choice. Use
the Compare & pull request banner on
https://github.com/OpenSAK-Org/OpenSAK-Macros, or click
compare across forks and set the base repository to
OpenSAK-Org/OpenSAK-Macros.
Title, for example: Update find-easy-traditionals to 1.1. Briefly say what
changed.
- Your own macro, green checks, nothing new declared: the pull request
gets the label
auto-mergeand is merged automatically. ✨ - New permission or new host declared: a maintainer reviews it first.
- Someone else's macro: a maintainer reviews it. It's best to talk to the owner first, in an issue or in Discussions.
- Only the README or example files changed: a version bump isn't required, but bumping does no harm.
Guide drafted by nagisml during the first test of this repository.