diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index 8ff29626..f65db3f4 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -272,7 +272,7 @@ 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. -#### Merging pull requests +#### 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 @@ -280,9 +280,28 @@ 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. +pass _when merged_, not just in the (possibly outdated) branch. -To merge a pull request, just add the merge me label. +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? @@ -309,10 +328,3 @@ 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. - -Having push access also means, of course, that you can push directly -to `main`. You are welcome to do so for typos, small fixes, -documentation improvements, and the like; for larger fixes, new -features, _etc._ you should still open a pull request from a feature -branch, to give a chance for others to offer suggestions for -improvement. diff --git a/README.md b/README.md index 08d6c2f1..aa9e139b 100644 --- a/README.md +++ b/README.md @@ -22,107 +22,25 @@ Swarm Swarm is a 2D programming and resource gathering game. Program your robots to explore the world and collect resources, which in turn allows you to build upgraded robots that can run more interesting and -complex programs. Check out the [installation -instructions](https://github.com/swarm-game/swarm#installing) below, -join the [IRC channel](COMMUNITY.md), take a look at the -[wiki](https://github.com/swarm-game/swarm/wiki), or [see how you can -contribute](CONTRIBUTING.md)! +complex programs. More info can be found on the [Swarm +website](https://swarm-game.github.io). -![World 0 after scanning a tree and making a log.](images/tutorial/log.png) +[![World 0 after scanning a tree and making a log.](images/tutorial/log.png)](https://swarm-game.github.io) -Features include: +Contributing +------------ -* Practically infinite 2D procedurally generated worlds -* Simple yet powerful programming language based on the polymorphic - lambda calculus + recursion, with a command monad for describing - first-class imperative actions -* Editor support with LSP and highlighting -* In-game tutorial -* Multiple game modes: - - In Classic mode, you start with the ability to produce only very - basic, limited robots; collecting resources allows you to - bootstrap your way into programming more sophisticated robots - that can explore more of the world, collect more resources, etc. - - Creative mode places no restrictions: program robots to your - heart's content using whatever language features you want, - without worrying about collecting resources. - - There are also challenge scenarios where you attempt to program - robots in order to solve pre-designed puzzles or challenges. +See [CONTRIBUTING.md](CONTRIBUTING.md) for information about various +ways you can contribute to Swarm development! -Installing -========== +Building +-------- -**NOTE**: Compiling Swarm with GHC 9.2.5 and optimizations enabled -seems to result in very long freezes/delays (tens of seconds) when -starting Swarm (see -[#1000](https://github.com/swarm-game/swarm/issues/1000)). We -recommend either building Swarm with a different version of GHC -(*e.g.* 9.4.x), or building with optimizations turned off (which does -not seem to affect the game performance very much). - -**NOTE**: Swarm requires a POSIX-style terminal environment that -supports `terminfo`. Linux and MacOS should work out of the box. On -Windows, you will need to use [Windows Subsystem for -Linux](https://learn.microsoft.com/en-us/windows/wsl/); you should -then be able to follow instructions for installing on Linux. - -It is recommended that you use a relatively large terminal window -(*e.g.* 170 columns x 40 rows or larger). To find out the size of -your terminal, you can type `stty size` at a command prompt. If it's -not big enough, try decreasing the font size. You can read about -and/or share recommended terminal settings in [this GitHub -issue](https://github.com/swarm-game/swarm/issues/447). - -- [Installing via binaries](#installing-via-binaries) -- [Installing from Hackage](#installing-from-Hackage) -- [Installing from source](#installing-from-source) - -Installing via binaries ------------------------ - -Currently we have one binary release built on [Ubuntu Bionic](https://github.com/docker-library/buildpack-deps/blob/98a5ab81d47a106c458cdf90733df0ee8beea06c/ubuntu/bionic/Dockerfile); it -will probably work on any GNU/Linux. We hope to add MacOS binaries in the -near future. - -You can download the `swarm` binary and compressed data directory from -the [latest release](https://github.com/swarm-game/swarm/releases). If -you want to run the binary simply as `swarm`, you have to put it in -one of the directories in your `PATH`: -```bash -chmod +x ./swarm # make it executable -echo $PATH | tr ':' '\n' # choose one of the listed directories -mv ./swarm /my/chosen/bin/directory/ -``` -You will also need to extract the data to your local Swarm folder so -the executable can find it: -```bash -mkdir -p ~/.local/share/swarm/ -unzip swarm-data.zip -d ~/.local/share/swarm -``` - -Installing from Hackage ------------------------ - -If you can't use the provided binaries, or prefer installing [from -Hackage](https://hackage.haskell.org/package/swarm), you should be -able to install with - - cabal install swarm - -If you don't already have the `cabal` tool, first [install -`ghcup`](https://www.haskell.org/ghcup/), then run `ghcup install -cabal` (if `cabal` was not automatically downloaded as part of -`ghcup`'s installation). - -You may need to add `~/.cabal/bin` to your `PATH`; alternatively, you -can install with `cabal install --installdir= swarm` to have -`cabal` install the `swarm` executable in a `` of your choosing. - -Installing from source ----------------------- - -If you want the latest unreleased bleeding-edge features, or want to -contribute to Swarm development, you can build from source. +If you just want to play the game, [head over to the Swarm website for +installation instructions](https://swarm-game.github.io/installing/). +If you want to build Swarm from source (*e.g.* in order to +[contribute](CONTRIBUTING.md), or to test out the latest bleeding-edge +unreleased features), read on. 1. Clone the Swarm repository, e.g. @@ -144,30 +62,5 @@ contribute to Swarm development, you can build from source. 1. Go get a snack while `stack` downloads a Haskell compiler and all of Swarm's dependencies. - -Configuring your editor -======================= - -Although you can write commands and definitions directly in the Swarm -REPL, once you get beyond the basics you'll probably want to use an -external editor for writing Swarm programs. Swarm has support for -external editors with highlighting and LSP integration: - -![Editor with problem popup](images/editor.png) - -See the [`editors` folder](editors/) for details on how to configure your editor. -Currently, emacs and VS Code are officially supported, but more can be -added. - -Community -========= - -Check out the [COMMUNITY](COMMUNITY.md) page for ways to connect with -others in the community. - -If you want to contribute, you're most welcome! There are *lots* of -ways to contribute, regardless of your Haskell background. For -example, even someone with no Haskell experience whatsoever could -still help with *e.g.* game design, playtesting, and creating -challenges and scenarios. Check out the [CONTRIBUTING](CONTRIBUTING.md) -file for more specific information about how to contribute. +1. You might also want to check out the `scripts` directory, which + contains an assortment of useful scripts for developers.