Step by Step tutorial of how to submit a PR

OpenDistro
1

Currently I am working on a PR for OpenSearch core. Because I am facing some difficulties and questions I want to document my efforts and write a tutorial on how to correctly submit a PR (with all the bells and whistles) to make it easier for others and encourage the community to do the same. Focus will be the surroundings, not so much the coding itself. The audience are experienced developers but with no special knowledge of the OpenSearch eco- or build system.

For now the plan is to use this thread to document by work and describe the challenges and their solutions. If finished (and the PR hopefully merged) I like to extract the relevant stuff into a external document (or blog post, … etc)

The main topics to develop bugfixes, enhancements or new functionalities for OpenSearch core and submit them are IMHO:

  • Prerequisites
    • Read the Code of Conduct
    • Understand the Developer Certificate of Origin (DCO)
    • Github account
  • Setting up the development environment
    • Git, Java, Docker, IDE, …
  • Cloning the repositories
  • Code something
    • Code Formatting
    • Javadoc
    • Forbidden Apis
    • Breaking changes
    • About public APIs and backward compatibility
    • Logging
    • What if I need a new external library
  • Write unittests (and probably integrationtests)
    • Run tests also with OpenSearch plugins installed (especially security)
  • Smoke testing (with a real cluster outside the IDE or build system/CI)
    • Assemble OpenSearch
    • Track and fix issues with the Java SecurityManager
  • Performance testing
    • Did I slow down OpenSearch (if the PR is not about performance)
    • Did I solve the performance issue (if the PR is actually about enhancing performance)
  • Run all the tests and prepare a commit
    • Squash and rebase
    • Pre commit checks
    • Write a proper commit message
    • Signing off
  • Submit PR
    • Open an issue (if not already existing)
    • Push the commit(s)
    • Fix CI issues
    • Mastering the review process
  • Documentation
    • Submit a PR for the docs
    • Write something for the release notes

Makes sense?
Anything missing?

1 Like
2

i would focus on documenting the OpenSearch-specifics. some of the things you mention are GitHub specific (how to work with PRs, forks, etc.), others are tooling specific (git, java, docker, IDE), etc. - all of which should already have good documentation. i think there it’s enough to just put a link to these documentations or even skip it completely (i somehow expect people who want to work on a search engine to know how to use a search engine, so they should be able to search with their favourite web search engine for the documentation on the tooling they want to use).

3

I think it’s pretty cool. Could be a good blog post such as “My first contribution to OpenSearch”.

Might be worth updating OpenSearch/CONTRIBUTING.md at main · opensearch-project/OpenSearch · GitHub with OpenSearch specifics, too.