Skip to content

Latest commit

 

History

History
214 lines (150 loc) · 9.17 KB

CONTRIBUTING.md

File metadata and controls

214 lines (150 loc) · 9.17 KB
Raw

Contribution Guide

There are many ways to be an open source contributor, and we're here to help you on your way! You may:

  • Propose ideas in our discord
  • Raise an issue or feature request in our issue tracker
  • Help another contributor with one of their questions, or a code review
  • Suggest improvements to our Getting Started documentation by supplying a Pull Request
  • Evangelize our work together in conferences, podcasts, and social media spaces.

This guide is for you.

Development Prerequisites

Requirement Tested Version Installation Instructions
Ruby 3.2.x, 3.3.x ruby-lang.org
Docker Engine 27.x docker.com
Docker Compose 2.29.x docker.com

Ruby

This project is written in Ruby, a dynamic, open source programming language with a focus on simplicity and productivity.

You may verify your ruby installation via the terminal:

$ ruby -v
ruby 3.3.4 (2024-07-09 revision be1089c8ec) [arm64-darwin23]

If you do not have Ruby, we recommend installing it using one of the following:

Ruby Dependencies

Ruby dependencies are managed using bundler, which comes installed with Ruby. To install Ruby dependencies, run:

$ bundle install

Once that is done, prefix Ruby commands with bundle exec in order to run them in the context of the project bundle.

Docker and Docker Compose

This project uses Docker Engine and Docker Compose to run Elasticsearch and OpenSearch locally. We recommend installing Docker Desktop to get both Docker dependencies.

Customizing the Development Environment

The project bundle only contains the gems necessary for what runs on CI. For local development, you may want to use some additional gems, such as:

Different engineers have different preferences around what gems to include, so the standard project bundle does not include gems like these. However, support is included to customize the development environment:

  • Make a Gemfile-custom file listing the additional gems you want to include. See Gemfile-custom.example for an example.
  • Run source script/enable_custom_gemfile.

This will set the BUNDLE_GEMFILE and BUNDLE_LOCKFILE environment variables in your shell session so that bundle exec will run in the context of your custom bundle.

Codebase Overview

To understand how the different parts of the codebase fit together, see the codebase overview.

Build Scripts and Executables

The codebase includes a variety of build scripts and executables which are useful for local development:

  • script/quick_build: Performs an abridged version of the CI build. This is generally the most complete CI build we run locally.
  • script/type_check: Runs a steep type check.
  • script/spellcheck: Spellchecks the codebase using codespell.
  • script/run_specs: Runs the test suite.
  • script/run_gem_specs [gem_name]: Runs the test suite for one ElasticGraph gem.

Running Tests

We use RSpec as our test framework.

Each of the ElasticGraph gems has its own test suite in spec (e.g. elasticgraph-support/spec contains the tests for elasticgraph-support).

Run the entire suite:

script/run_specs

To test a single gem (e.g., elasticgraph-support):

# From the root:
bundle exec rspec elasticgraph-support/spec

# Alternatively run a gem's specs within the context of that gem's bundle, with code coverage tracked:
script/run_gem_specs elasticgraph-support

# Alternatively, you can run tests within a subdirectory:
cd elasticgraph-support
bundle exec rspec

The RSpec CLI is extremely flexible. Here are some useful options:

# See RSpec CLI options
bundle exec rspec --help

# Run all specs in one directory
bundle exec rspec path/to/dir

# Run all specs in one file
bundle exec rspec path/to/dir/file_spec.rb

# Run the spec defined at a specific line in a file
bundle exec rspec path/to/dir/file_spec.rb:47

# Run only the tests that failed the last time they ran
bundle exec rspec --only-failures

# Run just failures, and halt after the first failure (designed to be run repeatedly)
bundle exec rspec --next-failure

Project Website

The source code for https://block.github.io/elasticgraph/ lives in config/site. To serve it locally, run:

bundle exec rake site:serve

Then visit http://localhost:4000/elasticgraph/ in your browser. Local edits to the site will be reflected when you reload a page.

API Documentation

ElasticGraph's Ruby code is documented using YARD. You can view the rendered API docs in the context of the project website using the same site:serve rake task (just visit http://localhost:4000/elasticgraph/docs/main/). However, that task fully regenerates the documentation from scratch and it's not very quick. If you're working on multiple changes to the API documentation, you'll get a faster feedback loop using the site:preview_docs:[gem name] tasks. For example, to preview the docs of elasticgraph-schema_definition, run:

bundle exec rake site:preview_docs:elasticgraph-schema_definition

Then visit http://localhost:8808/. The preview task will rebuild the parts of the generated docs impacted by your edits, and is quite fast.

Communications

Issues

Anyone from the community is welcome (and encouraged!) to raise issues via GitHub Issues.

Discussions

Design discussions and proposals take place on GitHub discussions. We advocate an asynchronous, written discussion model - so write up your thoughts and invite the community to join in!

In addition, we have a discord channel for synchronous communication. Discord is best for questions and general conversation.

Continuous Integration

Build and test cycles are run on every commit to every branch on GitHub Actions.

Contribution

We review contributions to the codebase via GitHub's Pull Request mechanism. We have the following guidelines to ease your experience and help our leads respond quickly to your valuable work:

  • Start by proposing a change either on Discord (most appropriate for small change requests or bug fixes) or in Discussions (most appropriate for design and architecture considerations, proposing a new feature, or where you'd like insight and feedback)
  • Cultivate consensus around your ideas; the project leads will help you pre-flight how beneficial the proposal might be to the project. Developing early buy-in will help others understand what you're looking to do, and give you a greater chance of your contributions making it into the codebase! No one wants to see work done in an area that's unlikely to be incorporated into the codebase.
  • Fork the repo into your own namespace/remote
  • Work in a dedicated feature branch. Atlassian wrote a great description of this workflow
  • When you're ready to offer your work to the project, first:
  • Squash your commits into a single one (or an appropriate small number of commits), and rebase atop the upstream main branch. This will limit the potential for merge conflicts during review, and helps keep the audit trail clean. A good writeup for how this is done is here, and if you're having trouble - feel free to ask a member or the community for help or leave the commits as-is, and flag that you'd like rebasing assistance in your PR! We're here to support you.
  • Open a PR in the project to bring in the code from your feature branch.
  • The maintainers noted in the CODEOWNERS file will review your PR and optionally open a discussion about its contents before moving forward.
  • Remain responsive to follow-up questions, be open to making requested changes, and... You're a contributor!
  • And remember to respect everyone in our global development community. Guidelines are established in our Code of Conduct.