CONTRIBUTING.md

April 16, 2026 ยท View on GitHub

Licensing

The lobsters codebase is under a 3-clause BSD license. All code submitted must be licensed under these or more-permissive terms (2-clause BSD, MIT, ISC, etc.).

The most important thing

Thanks for considering spending your time contributing to the codebase. Drop by the chat room if you'd like a hand getting started.

If you're new to Rails, the official guides are good and there's a complete API doc.

We consider contributions to be gifts, and there's no gift you can give that obligates you to give more gifts. If you reported an issue or opened a PR but don't want to continue with it, especially when a maintainer is asking for more info or revisions, please do tell us you're done with it so we know to carry on with it ourselves.

Getting oriented

If you're new to contributing, issues tagged good first issue require little knowledge of the codebase or community. Ask your questions in the issue or in our chat room, we'd love to help you get involved.

You can jump right in to issues tagged good first issue, you don't have to ask permission. Please don't post a comment to "claim" an issue. If an issue then doesn't get finished it stalls out for years because nobody wants to be rude and "steal" it.

Do not submit code written by LLM-powered coding tools because of the uncertainty around their output's copyright.

While this project's license allows for modification and use to run your own website, this source code repository is specifically for the code running the website at lobste.rs.

We're very deliberate about new features and behavior changes because they have difficult-to-foresee social effects or maintenance costs. If you have ideas, please come discuss them on /t/meta, in the chat room, or as a Github issue to avoid wasted effort.

Setting up your environment

  • Fork lobsters/lobsters on Github.

  • Clone your fork locally.

    $ git clone git@github.com:<your_gh_username>/lobsters.git
$ cd lobsters
lobsters$

  • Setup up your development environment with docker, using a devcontainer, or locally:

  • Install MariaDB:

  • Start the MariaDB server using one of the methods mentioned in the MariaDB knowledge base.

  • Open the console using mariadb, and set the root user password (type ctrl-d to exit afterwards):

    ALTER USER 'root'@'localhost' IDENTIFIED BY 'localdev';

  • Install the Ruby version specified in .ruby-version.

  • Install libvips

    Ubuntu/Debian:

    lobsters$ sudo apt install libvips

    Mac:

    lobsters$ brew install vips

  • Run bin/setup to install dependencies and set up the database:

    lobsters$ bin/setup

  • Run rails credentials:edit to create and edit your encrypted credentials file. This is where you store API keys for external services and features like linking accounts. Copy and paste in the contents of config/credentials.yml.enc.sample. On setup, Rails will give you new random value for secret_key_base and you can use rails secret any time you need to generate another.

  • If you intend to setup a production server, copy config/initializers/production.rb.sample to config/initializers/production.rb and customize it with your site's domain and name. (You don't need this on your dev machine.)

  • On your personal computer, you probably want to add some sample data:

    lobsters$ rails fake_data

    The default password for users generated by fake_data is "fake".

  • Run the Rails server in development mode. You should be able to log in to http://localhost:3000 with your new test user (with password test):

    lobsters$ rails server

Making your change

  • Create a branch to work on: git checkout -b ...

  • Write your commit messages in present tense ("fix foo", not "fixed foo"). Mention a GitHub issue number if there is one. Don't sweat messages too much, I am weirdly picky about commit messages so expect that I'll rewrite the message that merges/squashes the PR.

  • Our testing goal is to get good information and reasonable reliability with pretty low maintenance and runtime costs. We try to have a smoke test for the happy path of user-facing features and then test at least a few paths through more complicated functions. Not all changes require tests, but most bug fixes benefit from it.

  • You can "run the build" (see .github/workflows/check.yml) locally with bundle exec rake build, which runs the following:

    • rspec is the test suite. It's a big DSL so it has a pretty steep learning curve. It's easiest to get started by duplicating existing tests.

    • standardrb is the linter/formatter. There's very nice editor integration available.

    • brakeman is the security linter. You can run brakeman -I to interactively add a note if a new warning is a false positives. Brakeman is conservatively configured to "fail" when a new version of brakeman is released. If that happens when you're working on a PR, you can ping me and I'll update it.

      Brakeman also sometimes emits intimidating warnings about minor changes near known risky code. So if brakeman warns you about code you didn't write, don't panic, it's probably fine. Push your PR and @mention me, I'll help sort it out.

    • database_consistency checks for inconsistencies between the database schema and Active Record models.

Sharing your work

  • Push your changes to your fork of the repository: git push origin

  • Open a pull request to lobsters/lobsters. You're welcome to open a PR for a work in progress if you want to share progress or ask for help. It's a big help if you explicitly write in a comment whether the code is a draft or is ready to merge!

  • If I request changes to the PR, you can add more commits or edit your existing and force-push, whatever you prefer. I usually squash and rebase small PRs and merge PRs where the commits are big enough to be individually useful in future debugging. I don't have a particularly strong opinion and I want to treat your work respectfully, so please do let me know if you prefer squash/rebase/merge.