OpenFn / OpenFn/lightning

Remove duplicate instructions for running locally from `README.md`

Open
#2,812 0 comments 0 reactions 0 assignees View on GitHub

Nobody has claimed this yet.

Dominant language
Elixir
Stars
296
Forks
86
Avg merge
1d 13h
Merged PRs (30d)
50

Description

We've got lots of duplicate code between README.md and RUNNINGLOCAL.md. Why do we have a RUNNINGLOCAL.md file?

If the answer is [ good reasons ] then we should DRY up the implementation. We shouldn't duplicate this code—that means we'd have to maintain two separate sets of instructions—but instead:

  1. delete everything in the README and in the section where we used to explain how to dev locally;
  2. provide a link to where the new instructions live; and
  3. change the title of the document from RUNNINGLOCAL.md to DEVELOPMENT.md. The official way to run lightning locally is the first section under "Getting Started" and requires docker: https://openfn.github.io/lightning/readme.html#run-via-docker.

What's being described in this new file, it seems, is how to build stuff using Erlang and Elixir from scratch in case you want to do local development. This is the Dev on Lightning Locally section.

Details

We have a separate guide for running lightning locally in RUNNINGLOCAL.md. Some of the instructions are exact duplicates of the instructions in README.md.

We should remove the duplicate instructions from README.md and instead have links that point to the RUNNINGLOCAL.md.

Originally posted by @taylordowns2000 in https://github.com/OpenFn/lightning/pull/2801#pullrequestreview-2545484812

Contributor guide

No contributing guide indexed for this repository

First steps

  1. Read the whole issue, then the project's contributing guide.
  2. Comment on the issue to say you are picking it up — it saves two people doing the same work.
  3. Fork the repository and make your change on a branch.
  4. Open a pull request that references the issue number.

Research direction

Read README.md and RUNNINGLOCAL.md, comparing the duplicated local-development instructions and the linked "Dev on Lightning Locally" section. Remove the duplicate README.md content, rename RUNNINGLOCAL.md to DEVELOPMENT.md, and update the links so the documentation has one authoritative set of instructions.

Written by the indexing model from the issue text.

Assessment

Tech stack
elixir, erlang
Domain
documentation
Issue type
Documentation
Difficulty
2/5
Estimated time
1-3 hours
Activity status
Stale
Clarity
Mostly clear
Newbie friendliness
35/100

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.