Skip to content

Contributing to Sanmill

Jump to bottom
Calcitem edited this page Oct 31, 2021 · 8 revisions

Contributing to Sanmill

Thanks for taking the time to contribute to Sanmill!

Nevertheless, you can use GitHub to send your Pull Requests commits to us conveniently.

In addition, we highly recommend you read our submission guidelines.

Your friendly Sanmill community!

Submission guidelines

Here are some guidelines for people who want to contribute their code to this software.

Base branch

Decide what to base your work on.

In general, always base your work on the oldest branch that your change is relevant to.

  • A bugfix should be based on maint in general. If the bug is not present in maint, base it on master. For a bug that's not yet in master, find the topic that introduces the regression and base your work on the tip of the topic.

  • A new feature should be based on master in general if the new feature depends on a topic in dev, but not in master, base your work on the tip of that topic.

  • Corrections and enhancements to a topic not yet in master should be based on the tip of that topic. If the topic has not been merged to dev, it's alright to add a note to squash minor corrections into the series.

  • In the exceptional case that a new feature depends on several topics not in master, start working on dev privately and create pull requests for discussion. Before the final merge, you may have to wait until some of the dependent topics graduate to master, and rebase your work.

To find the tip of a topic branch, run git log --first-parent master..dev and look for the merge commit. The second parent of this commit is the tip of the topic branch.

Separate commits

Make separate commits for logically separate changes.

Unless your commit is trivial, you should make separate commits for logically separate changes.

Explain the change(s) that is detailed enough to judge if it is good to do without reading the actual commit message to determine how well the code does what the explanation promises to do.

If your description starts to get too long, that's a sign that you probably need to split up your Git commit to finer-grained pieces. That being said, Git commits that plainly describe the things that help reviewers check the commit and future maintainers understand the code is the most beautiful commits. Descriptions that summarize the point in the subject well and describe the motivation for the change, the approach is taken by the change, and, if relevant, how this differs substantially from the prior version are all good things to have.

Make sure that you have tests for the bug you are fixing.

Whitespace check

Oh, another thing. We are picky about whitespaces. To help ensure this does not happen, run git diff --check on your changes before you Git commit.

Describe changes

Describe your changes well.

The commit message's first line should be a short description (50 characters is the soft limit) and should skip the full stop. It is also conventional in most cases to prefix the first line with "area: " where the area is a filename or identifier for the general area of the code being modified, e.g.

  • doc: Clarify the distinction between sign-off and PGP-signing
  • Readme.md: Improve the intro section

If in doubt which identifier to use, run git log --no-merges on the files you are modifying to see the current conventions.

Summary section

The title sentence after the "area:" prefix omits the full stop at the end.

Meaningful message

The body should provide a meaningful commit message, which:

  • Explains the problem the change tries to solve, i.e., what is wrong with the current code without the change.

  • Justifies how the change solves the problem, i.e., why the result is better.

  • Alternate solutions considered but discarded if any.

Imperative mood

Describe your changes in imperative mood, e.g., "Make xyzzy do frotz" instead of "Makes xyzzy do frotz" or "Changed xyzzy to do frotz", as if you are giving orders to the codebase to change its behavior. Try to make sure your explanation can be understood without external resources. Instead of providing a URL to an issue, summarize the relevant points of the discussion.

Review commit

Please make sure your commit does not add commented-out debugging code or include any extra files which do not relate to what your commit is trying to achieve. Make sure to review your commit after generating it to ensure accuracy. Before sending it out, please make sure it cleanly applies to the master branch head. If you are preparing work based on the dev branch, that is fine, but please mark it as such.

Commit flow

An ideal commit flow

Here is an ideal commit flow for this project the current maintainer suggests to the contributors:

  1. You come up with an itch. You code it up.
  2. A topic branch is created with the commit, creates a pull request, and assigns people who may need to know about the change.

The people who may need to know are the ones whose code you are butchering. These people happen to be the ones who are most likely to be knowledgeable enough to help you, but they have no obligation to help you (i.e., you ask for help, don't demand).

  1. You get comments and suggestions for improvements. You may even get them in an "on top of your change" commit form.

  2. Polish, refine, and re-push. Go back to step (2).

  3. The pull request forms consensus that the last round of your commit is good.

  4. The topic branch is merged or rebased to dev, cooked further, and eventually graduates to master.

Commit status

Know the status of your commit after submission

You can use Git itself to find out when your commit is merged in master. git pull --rebase will automatically skip already-applied Git commits and let you know. This works only if you rebase on top of the branch in which your commit has been merged (i.e., it will not tell you if your Git commit is merged in dev if you rebase on top of master).

GitHub CI

With an account at GitHub, you can use GitHub CI to test your changes on Linux, Mac, and Windows. See https://github.com/calcitem/Sanmill/actions for examples of recent CI runs.

Follow these steps for the initial setup:

CI will run after the initial setup whenever you push new changes to your fork of Git on GitHub. You can monitor the test state of all your branches here: https://github.com/<Your GitHub handle>/Sanmill/actions/.

If a branch did not pass all test cases, then it is marked with a red cross. In that case, you can click on the failing job. You can also download "Artifacts" which are tarred (or zipped) archives with test data relevant for debugging.

Then fix the problem and push your fix to your GitHub fork. This will trigger a new CI build to ensure all tests pass.

Clone this wiki locally