15 KiB
Contributing to Swarm
Thanks so much for taking the time to contribute to Swarm! All contributions are welcomed and appreciated, whether reporting a bug or fixing a single punctuation mark, contributing to game design, or implementing a complex new feature.
The following is a set of guidelines for contributing to Swarm, which
is hosted in the swarm-game/swarm
repository
on GitHub. These are mostly guidelines, not rules. In particular, you
don't need to worry that your contribution will be ignored or rejected
in some way if you don't follow the guidelines. Use your best
judgment, and also feel free to propose changes to this document in a
pull request.
Table Of Contents
- Reporting Bugs
- Suggesting Enhancements
- Contributing to Game Design
- Making a Code Contribution
- Development Workflow
- Conventions
I have push access to the Swarm repository, now what?
Code of Conduct
The Swarm project and everyone participating in it is governed by the Contributor Covenant Code of Conduct. By participating, you are expected to uphold this code. Please report unacceptable behavior to byorgey@gmail.com.
Quick Links
- Bug to report or feature to request? Try the GitHub issue tracker.
- Questions? Join the
#swarm
IRC channel on the Libera.Chat network. If you're not familiar with IRC you can easily connect via this web client.
How can I contribute?
There are lots of ways to contribute to Swarm. Regardless of your background knowledge or level of programming skill, there is probably a way you can help. For general advice on contributing to open source projects like Swarm, see How to Contribute to Open Source, or Your first open source contribution: a step-by-step technical guide. The rest of this section walks through specific ways you can contribute and instructions for how to do so.
Reporting Bugs
Even if you're not at the point where you would feel comfortable contributing code or documentation, simply playing the game and reporting any problems that you find or suggestions you have along the way is an immensely valuable way to help make the game better.
Feel free to submit a bug report for anything that seems like it's not the way it should be, such as a typo or inconsistency in some in-game text, a robot program that yields an error even though you think it should be accepted, or a robot program that seems to behave incorrectly. Even if the error turns out to be in your understanding rather than in the game, it's still a valuable contribution, since it may point out a way that the documentation or interface could be improved to help reduce similar confusion in the future.
Bugs are tracked as GitHub issues. Before creating a new issue, you can do a quick search to see if the problem has already been reported. If it has and the issue is still open, feel free add a comment to the existing issue instead of opening a new one.
When creating a new issue, explain the problem and include additional details to help the maintainers reproduce the problem, for example:
- Use a clear and descriptive title for the issue to identify the problem, if you can.
- Provide specific examples to demonstrate the problem. In many cases this may be in the form of some specific Swarm code which causes the problem to happen. To include some Swarm code in the issue, you can use Markdown code blocks.
- Describe the behavior you observed after following the steps and point out what exactly is the problem with that behavior.
- Explain which behavior you expected to see instead and why.
Not all of these are necessarily required for every single bug report; use your judgment, but try to err on the side of including more information.
Suggesting Enhancements
If you have an idea for a way Swarm could be better, or a super-cool new feature you'd like to see, you can submit it on the GitHub issue tracker, the same as a bug report. Just describe your idea in as much detail as you can.
Contributing to Game Design
You are very much encouraged to help think about game design: how new language features, entities, devices, and world features should be added and changed, and how they all fit together to deepen the game and create possibilities of gameplay. Take a look at the DESIGN document in this repository for some overarching thoughts and principles about the design of the game.
If you have a concrete idea that you think will work well, you can try implementing it and opening a pull request. However, if you have an idea you are unsure about, or if you just want to help think through some ideas but lack the skill, time, or desire to implement them, feel free to just open an issue with a description of your ideas to create a space for discussion.
Making a Code Contribution
Swarm is written in Haskell. The level of
Haskell skill needed to understand and contribute to the Swarm
codebase varies widely depending on which part of the code you look
at, but generally speaking you will probably need to be comfortable
with standard monads (Except
, Reader
, State
, Maybe
) and with
standard container types like Data.Set
and Data.Map
. Being
familiar with using lens
will probably also help. If you'd like to
learn enough Haskell to contribute to Swarm, we recommend starting by
working through these introductory Haskell course
materials.
If you'd like to contribute some code but are unsure where to begin,
you can start by looking through issues tagged "Low-Hanging
Fruit"
in the issue tracker. These are bugs and features which should be
appropriate for someone just getting started to tackle. If you want
help understanding or getting started on a particular issue, feel free
to leave a comment on the issue, or ask in the #swarm
IRC
channel on Libera.Chat.
Development Workflow
Never made an open source contribution before? Wondering how making a contribution actually works? Here's a quick rundown! If you're already comfortable contributing to open source, you can skip to the Conventions.
- Find an issue that you are interested in addressing or a feature that you would like to add.
- Fork the
swarm
repository (by clicking the "Fork" button in the upper-right corner). This will make a copy of the repository in your personal GitHub account, that is, you will have your own personal copy of the repository under<your-GitHub-username>/swarm
. - Clone the repository to your local machine by opening a terminal,
navigating to the directory where you would like to store the
swarm
repository, and typinggit clone https://github.com/your-GitHub-username/swarm.git
. (If you don't already have thegit
tool, you will have to install it first.) You should now have a subfolder namedswarm
containing an up-to-date copy of the repository. - Create a new branch for your fix using
git checkout -b BRANCH-NAME
(replaceBRANCH-NAME
by some appropriate name based on the feature or fix you plan to make). - Make the appropriate changes for the issue you are trying to address or the feature that you want to add.
- Use
git add
to add the file contents of the changed files to the "snapshot" git uses to manage the state of the project, also known as the index. - Use
git commit -m "Insert a short message of the changes made here"
to store the contents of the index with a descriptive message. - Push the changes to your fork on GitHub using
git push origin BRANCH-NAME
. - Submit a pull request
from your fork to the
swarm-game/swarm
repository. - Title the pull request with a short description of the changes made and the issue or bug number associated with your change (if any). For example, you can title an issue like so "Added more log output to resolve #4352".
- In the description of the pull request, explain the changes that you made, any issues you think exist with the pull request you made, and any questions you have for the maintainer. It's OK if your pull request is not perfect (no pull request is), the reviewer will be able to help you fix any problems and improve it!
- Wait for the pull request to be reviewed by a maintainer.
- Make changes to the pull request if the reviewing maintainer recommends them.
You can simply make additional changes,
add
andcommit
them, and thenpush
to the same branch. Any additional commits added to the same branch will automatically be included in the pull request. - Celebrate your success after your pull request is merged!
- After your first pull request is merged, it is very likely that you will be
granted push access to the
swarm-game/swarm
repository. This means that from now on you can create branches directly within theswarm
repository rather than working in your own fork. For more information, see I have push access to the Swarm repository, now what?.
As a note, if you want to use the Stack tool with HLS,
check the hie.yaml.stack
file. Pure Cabal should work fine with the defaults,
but you might want to add a GHC flag
to build docs into cabal.project.local
.
TIP: To run tests, you can use the scripts/run-tests.sh
script to avoid problems with incremental compilation in alternation with stack build
.
Conventions
We follow a few conventions to help keep everyone on the same page. Please open a pull request or ask on IRC if you have any questions or suggestions.
More conventions will be added as we think of and/or come up with them!
Formatting style
We use fourmolu-0.13.0.0
with a custom
configuration
for formatting Haskell code.
To install the formatter, run:
cabal install fourmolu-0.13.0.0
If this installation does not work, you may have to set your GHC to a version supported by fourmolu
:
ghcup install ghc 9.4.5
and/or:
ghcup set ghc 9.4.5
You can run the formatter from the shell:
cd path/to/the/root/of/swarm/repo
fourmolu --mode=inplace src app test
For convenience, one may alternatively execute this script:
scripts/reformat-code.sh
There is probably a way to configure your favorite editor to have fourmolu
automatically applied to your code; but if you don't know how to set that up,
don't worry! The restyled.io
bot automatically
reformats pull requests as necessary.
Branches in the main repository
If you are a repository contributor (see I have push access to the
Swarm repository, now
what?), you
should create new contributions as branches in the swarm repository
itself (as opposed to in your own fork), unless you have a good
reason for doing otherwise. Then you can open a pull request from
the branch to main
. This eases collaboration and makes CI go more
smoothly (for example, the restyled.io
bot works much better on
pulls from local branches than from forks).
Draft pull requests
Feel free to open a pull request very early in the process, and mark it as a draft. This way you can get feedback (and even allow others to contribute) as you go.
Pull request workflow
Pull requests should be merged by the mergify
bot rather than by
hand. PRs will be merged as a single squashed commit, using the
title and description of the pull request, so make sure that they
give a good overview of the content of the PR.
This workflow is preferable because it makes sure that the changes pass when merged, not just in the (possibly outdated) branch.
Before being merged, a pull request must have at least one approving review (and no reviews marked "request changes"). To merge a pull request, just add the merge me label. Our typical workflow is as follows:
- A contributor opens a pull request from a branch, possibly marked as a draft if it's still being worked on
- Once the PR is ready for review, the contributor changes it from draft to ready status, and (optionally) requests a review from one or more other contributors.
- If changes are requested, the contributor can continue pushing additional commits to the PR branch. Note that when merged, the PR will be squashed into a single commit, so it's not particularly important to have a clean commit history on the PR branch.
- Often, if the reviewer has only minor changes to suggest, they can leave some comments suggesting changes and approve the pull request. This indicates trust in the PR author to make appropriate changes before merging.
- Typically, the reviewer(s) will leave it to the original PR author
to apply the
merge me
label once they are happy with it.
I have push access to the Swarm repository, now what?
Inspired by Edward Kmett, Swarm uses The Pull Request Hack: anyone who submits a pull request to Swarm is likely to be granted push access in short order.
One benefit is that when working on a new feature, you can create a branch in
the swarm
repository itself (instead of in your own fork) and then open a pull
request from the feature branch to main
. This is actually preferred since
it makes several things smoother (for example, the restyled.io
bot works much
better on pulls from local branches than from forks).
Although being given push access does not imply any particular
responsibility, you are welcome to do things such as help review and
merge other pull requests (use the merge me
label to trigger the
mergify process), and help triage, label, and update issues in the
issue tracker. When giving feedback on a pull request, try to be more
generous in what you accept from newer contributors---the code can be
fixed up later if necessary, and it's more important to help them feel
welcome and that their contribution is valued. More experienced
contributors can be held to a higher standard.