How to contribute

This document explains how to contribute to Horse64. If you want to help out then please read on.

Contribute testing feedback

If you want to help testing, get the SDK, play with it, and report bugs. Here's a setup guide.

Contribute code

If you want to contribute code to core tooling, please read:

  1. For now, many tests expect to run on Linux. If you contribute a bigger feature, you'll need to test on Linux according to the checklists. It's possible to do basic tests and changes on Windows if it's parts written in Horse64 (rather than Moose64 or C).

  2. Read the licensing carefully and agree to contribute your code under the given terms. ⚠️ We currently ask you don't use AI-based code generation or completion, like "Co-Pilot" etc. ⚠️

  3. Changes are done via pull requests in the respective repositories.

    To set up a new pull request, try these steps (warning, you should know terminal basics like changing directories):

    1. Make an account on codeberg.org:

      Also, install git for Windows and a text editor for editing code.

    2. Browse to the respective Horse64 project repository for whatever tool you want to patch on Codeberg.

    3. Click the "Fork" button on the codeberg page of the repository to get a personal fork, that's your own separate project copy:

    4. Clone your personal fork to your local machine with:

      git clone ...url-to-your-repo-fork-on-codeberg...
      

      Run that in a terminal, on Windows use e.g. the git cmd terminal of Git for Windows:

      Then cd into the directory in your terminal and switch to a new branch:

      git checkout -b name-for-your-branch
      
    5. Implement and test your change.

    6. Make sure to set up a name and e-mail with your local git if you haven't yet:

      git config user.name "John Doe"
      git config user.email "my-mail@example.com"
      
    7. Now use:

      git commit -a
      

      ...to save and describe your changes to your local repository. Make sure to add your developer certificiate of origin signature, see the license file.

      (If you added any new files, you might first need to use git add name-of-file.)

      Then use:

      git push origin name-for-your-branch
      

      ...to push your change to your personal fork online.

    8. Now go to the original repository on Codeberg, not your fork, go to "Pull Requests", and use "New Pull Request":

      For the "merge into" setting, make sure it's set to the project's original "main" branch. For "pull from", pick your personal fork and your name-for-your-branch branch.

If you want to talk to other developers, join the 💬 community chat.

Contribute documentation

You can find the documentation, including this file itself, in the main repository of the core.horse64.org package, it's inside the docs folder. Feel free to suggest improvements. ⚠️ We currently ask you don't use AI-based texts or suggestions, like ChatGPT etc. ⚠️

Contribute funding

There's no way to donate to the project itself.

Maintainer checklists

These are maintainer checklists for all the core projects:

Pull request checklist for core tooling

If you contribute a pull request... FIXME

Updating git hooks or issue forms

Whenever updating the git hooks, or the forms in the .gitea directory, or the workflows to disable pull requests in the .github directory, update them in the core.horse64.org main repository first.

Then run (in the main repository directory):

python3 maintainer-helper-update-repos.py

...to propagate the changes to all the other repository.

(The other repositories need to be cloned to neighboring repository directories, neighboring your core.horse64.org repository directory.)

Update all copyright notices for the next year

To update all copyright notices for the next year, do the same steps as for updating the git hooks for all repositories.

Release checklist for core tooling

This release checklist should be completed before attempting any release of what is part of the core tooling.

What is part of the core tooling: This list continuously expands and is made up of what is needed to build horp, HVM, and the standard library. The authoritative latest list for what is part of that, is maintained as part of tools/maintainer_helper_test_major_builds.h64 in the core.horse64.org main repository.

Steps required before any official release of core tooling:

  1. Be on Linux.

  2. Set up the core tooling repository directories next to each other in the versions to be tested, including what you plan to release.

  3. Run this and follow the instructions:

    translator/horsec_run.py tools/maintainer_helper_test_major_builds.h64
    

    (Run it in the core.horse64.org even if your change is in a different package.)

  4. If it reports an error at any point, it should be fixed before a release.

  5. Now you should run whatever tests the respective project or package offers. For HVM, that would usually be make test, and for the others that would usually be via horp test. If there are any errors, make sure to investigate if any are new!

Privacy | Admin Contact | Misc