Minimum Viable Contributing Guide + Readme updates (livepeer#2192)

* build basic guides * new files * fix link * fix typo * remove reference to sdk * remove more sdk references * fix links Co-authored-by: Hunter Hillman <[email protected]>
yunthornhill1 · Jan 27, 2022 · ec458db · ec458db
1 parent bc41dda
commit ec458db
Show file tree

Hide file tree

Showing 4 changed files with 205 additions and 43 deletions.
diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md
@@ -0,0 +1,136 @@
+# Contributing to go-livepeer
+
+Hey there, potential contributor!
+
+Thanks for your interest in this project. Every contribution is welcome and
+appreciated. We're super excited to help you to get started 😎
+
+> **Note:** If you still have questions after reading through this guide,
+> [open an issue](https://github.com/livepeer/go-livepeer/issues) or
+> [talk to us on Discord](https://discordapp.com/invite/7wRSUGX).
+
+### How You Can Help
+
+go-livepeer contributions will generally fall into one of the following
+categories:
+
+#### 📖 Updating documentation
+
+This could be as simple as adding some extra notes to a README.md file, or as
+complex as creating some new `package.json` scripts to generate docs. Either
+way, we'd really really love your help with this 💖. Look for
+[open documentation issues](https://github.com/livepeer/go-livepeer/labels/type%3A%20documentation),
+create your own, or submit a PR with the updates you want to see.
+
+If you're interested in updating user (e.g., node operator) documentation, please refer to [the relevant documentation on livepeer.org](https://docs.livepeer.org/contributing/overview).
+
+#### 💬 Getting involved in issues
+As a starting point, check out the issues that we've labeled as 
+[help wanted](https://github.com/livepeer/go-livepeer/labels/help%20wanted)
+and
+[good first issues](https://github.com/livepeer/go-livepeer/labels/good%20first%20issue).
+
+Many issues are open discussions. Feel free to add your own concerns, ideas, and
+workarounds. If you don't see what you're looking for, you can always open a new
+issue. 
+
+#### 🐛 Fixing bugs, 🕶️ adding feature/enhancements, or 👌 improving code quality
+
+If you're into coding, maybe try fixing a
+[bug](https://github.com/livepeer/go-livepeer/issues?q=is%3Aissue+is%3Aopen+label%3A%22type%3A+bug%22)
+or taking on a
+[feature request](https://github.com/livepeer/go-livepeer/issues?q=is%3Aissue+is%3Aopen+label%3A%22type%3A+feature%22+).
+
+If picking up issues isn't your thing, no worries -- you can always add more
+tests to improve coverage or refactor code to increase maintainability. 
+
+> Note: Bonus points if you can delete code instead of adding it! 👾
+
+#### 🛠️ Updating scripts and tooling
+
+We want to make sure go-livepeer contributors have a pleasant developer
+experience (DX). The tools we use to code continually change and improve. If you
+see ways to reduce the amount of repetition or stress when it comes to coding in
+this project, feel free to create an issue and/or PR to discuss. Let's continue
+to improve this codebase for everyone.
+
+> Note: These changes generally affect multiple packages, so you'll probably
+> want to be familiar with each project's layout and conventions. Because of
+> this additional cognitive load, you may not want to begin here for you first
+> contribution.
+
+## FAQ
+
+### How much do I need to know about peer-to-peer/livestreaming/go/etc to be an effective contributor?
+
+We expect a rich mixture of commits, conversation, support, and review. Adding documentation or opening issues are incredibly useful ways to
+get involved without coding at all. If you do want to contribute code, however,
+it'd be good to have some proficiency with go.
+
+### How is a contribution reviewed and accepted?
+
+- **If you are opening an issue...**
+
+  - Fill out all required sections for your issue type. Issues that are not
+    filled out properly will be flagged as `need: more info` and will be closed if not
+    updated.
+  - _Keep your issue simple, clear, and to-the-point_. Most issues do not
+    require many paragraphs of text. In fact, if you write too much, it's
+    difficult to understand what you are actually trying to communicate.
+    **Consider
+    [starting a discussion](https://github.com/livepeer/go-livepeer/discussions/new)
+    if you're not clear on something or want feedback from the community.**
+
+- **If you are submitting a pull request...**
+  - Write tests to increase code coverage
+  - Tag the issue(s) your PR is closing or relating to
+  - Make sure your PR is up-to-date with `master` (rebase please 🙏)
+  - Wait for a maintainer to review your PR
+  - Push additional commits to your PR branch to fix any issues noted in review.
+  - Wait for a maintainer to merge your PR
+
+
+### Changelog
+
+Every change (feature, bug fix, etc.) should be made in a PR that includes an update to the `CHANGELOG_PENDING.md` file which tracks the set of changes that will be included in the next release.
+
+Changelog entries should be formatted as follows:
+
+```
+- \#xxx Description of the change (@contributor)
+```
+
+`xxx` is the PR number (if for whatever reason a PR number cannot be used the issue number is acceptable) and `contributor` is the author of the change. The full link to the PR is not necessary because it will automatically be added when a release is created, but make sure to include the backslash and pound i.e. `\#2313`.
+
+Changelog entries should be classified based on the `livepeer` mode of operation that they pertain to i.e. General, Broadcaster, Orchestrator, Transcoder.
+
+Breaking changes should be documented in the "Breaking changes" section. Any changes that involve pending deprecations (i.e. a flag will be removed in the next release) should be documented in the "Upcoming changes" section.
+
+
+### When is it appropriate to follow up?
+
+You can expect a response from a maintainer within 7 days. If you haven’t heard
+anything by then, feel free to ping the thread.
+
+### How much time is spent on this project?
+
+Currently, there are several teams dedicated to maintaining this project.
+
+### What types of contributions are accepted?
+
+All of the types outlined in [How You Can Help](#how-you-can-help).
+
+### What happens if my suggestion or PR is not accepted?
+
+While it's unlikely, sometimes there's no acceptable way to implement a
+suggestion or merge a PR. If that happens, maintainer will still...
+
+- Thank you for your contribution.
+- Explain why it doesn’t fit into the scope of the project and offer clear
+  suggestions for improvement, if possible.
+- Link to relevant documentation, if it exists.
+- Close the issue/request.
+
+But do not despair! In many cases, this can still be a great opportunity to
+follow-up with an improved suggestion or pull request. Worst case, this repo is
+open source, so forking is always an option 😎.
diff --git a/README.md b/README.md
@@ -1,35 +1,71 @@
+<!-- show-on-docup
+<br />
+-->
+
+[![go-livepeer](https://user-images.githubusercontent.com/555740/117340053-78210e80-ae6e-11eb-892c-d98085fe6824.png)](https://github.com/livepeer/go-livepeer)
+
+---
 [![Go Report Card](https://goreportcard.com/badge/github.com/livepeer/go-livepeer)](https://goreportcard.com/report/github.com/livepeer/go-livepeer)
 [![Discord](https://img.shields.io/discord/423160867534929930.svg?style=flat-square)](https://discord.gg/7wRSUGX)
-[![license](https://img.shields.io/badge/license-MIT-blue.svg?style=flat-square)](https://github.com/livepeer/go-livepeer/blob/master/LICENSE)
+[![license](https://img.shields.io/badge/license-MIT-blue.svg?style=flat-square)](LICENSE.md)
+[![Contributions welcome](https://img.shields.io/badge/contributions-welcome-orange.svg?style=flat-square)](CONTRIBUTING.md)
+
+The Livepeer project aims to deliver a live video streaming network protocol
+that is fully decentralized, highly scalable, crypto token incentivized, and
+results in a solution which can serve as the live media layer in the
+decentralized development (web3) stack. You can learn more about the protocol
+and economic incentives by reading
+[our docs](https://docs.livepeer.org/protocol/overview).
+
+go-livepeer is a Go implementation of the [Livepeer](https://livepeer.org) protocol which powers the Livepeer Network. Specifically, go-livepeer contains implementations of broadcaster, orchestrator, and transcoder nodes on the Livepeer Network
+
+<!-- hide-on-docup-start -->
+
+## Table of Contents
+
+- [Requirements](#requirements)
+- [Getting Started](#getting-started)
+- [Contributing](#contributing)
+- [Other Documentation](#documentation)
+- [Resources](#resources)
+
+<!-- hide-on-docup-stop -->
+
+## Requirements
 
-# go-livepeer
+This project requires `go`. A unix shell is also
+required.
 
-go-livepeer is a Go implementation of the [Livepeer](https://livepeer.org) protocol which powers the Livepeer network, a decentralized video streaming
-network built on the Ethereum blockchain.
+- [Installing and Managing Go](doc/go.md)
 
-## Documentation
 
-- User documentation can be found at https://livepeer.org/docs
-- Developer documentation (i.e. if you are interested in developing go-livepeer) can be found in the [docs](doc) folder
-- Protocol information can found in the [protocol](https://github.com/livepeer/protocol) repo
-- Other project information can be found in the [wiki](https://github.com/livepeer/wiki/wiki)
+## Getting Started
 
-## Install Livepeer
+To get started, clone the repo and follow the [installation guide](https://docs.livepeer.org/installation/install-livepeer/installing-for-development#build-and-install).
 
-Follow the [installation guide](https://livepeer.org/docs/installation/install-livepeer/overview).
+Next, follow [the guide to set up a private ETH network with the Livepeer protocol deployed](cmd/devtool/README.md).
 
-## Run Livepeer
+## Contributing
 
-If you are interested in participating using the network as a video developer, check out the [video developer docs](https://livepeer.org/docs/video-developers/overview).
+Thanks for your interest in contributing to go-livepeer. There are many ways you can contribute.
+To start, take a few minutes to look over the official guide:
 
-If you are interested in participating in the network as a video miner, check out the [video miner docs](https://livepeer.org/docs/video-miners/overview).
+**[Read the "Contributing to go-livepeer" Guide &raquo;](CONTRIBUTING.md)**
 
-## Contribute
+We happily await your pull requests and/or involvement in our
+[issues page](https://github.com/livepeer/go-livepeer/issues) and hope to see
+your username on our
+[list of contributors](https://github.com/livepeer/go-livepeer/graphs/contributors)
+🎉🎉🎉
 
-Thank you for your interest in contributing to go-livepeer!
+## Resources
 
-To get started:
+To get a full idea of what Livepeer is about, be sure to take a look at these
+other resources:
 
-- Read the [contribution guide](doc/contributing.md)
-- Check out the [open issues](https://github.com/livepeer/go-livepeer/issues)
-- Join the #dev channel in the [Discord](https://discord.gg/uaPhtyrWsF)
+- 🌐 [The Livepeer Website](https://livepeer.org)
+- 📖 [The Livepeer Docs](https://livepeer.org/docs)
+- 🔭 [The 10-Minute Primer](https://livepeer.org/primer/)
+- ✍ [The Livepeer Blog](https://medium.com/livepeer-blog)
+- 💬 [The Livepeer Chat](https://discord.gg/uaPhtyrWsF)
+- ❓ [The Livepeer Forum](https://forum.livepeer.org/)
diff --git a/cmd/devtool/README.md b/cmd/devtool/README.md
@@ -5,23 +5,29 @@ An on-chain workflow testing tool that supports the following:
 - Automatically submitting the necessary setup transactions for each node type
 - Generating a Bash script with default CLI flags to start each node type
 
-This tool requires access to an ETH node connected to private network.
+## Prerequisites
 
-## Setting up a private ETH network
+## Step 1: Set up a private ETH network with Livepeer protocol deployed
 
 ```
-docker pull livepeer/geth-with-livepeer-protocol:pm
-docker run -p 8545:8545 -p 8546:8546 --name geth-with-livepeer-protocol livepeer/geth-with-livepeer-protocol:pm
+docker pull livepeer/geth-with-livepeer-protocol:streamflow
+docker run -p 8545:8545 -p 8546:8546 --name geth-with-livepeer-protocol livepeer/geth-with-livepeer-protocol:streamflow
+
+# Mac M1 ONLY
+# docker pull darkdragon/geth-with-livepeer-protocol:streamflow
+# docker run -p 8545:8545 -p 8546:8546 --name geth-with-livepeer-protocol darkdragon/geth-with-livepeer-protocol:streamflow
+
 ```
 
-## Setting up a broadcaster
+
+## Step 2: Set up a broadcaster
 
 `go run cmd/devtool/devtool.go setup broadcaster`
 
 This command will submit the setup transactions for a broadcaster and generate the Bash script
 `run_broadcaster_<ETH_ACCOUNT>.sh` which can be used to start a broadcaster node.
 
-## Setting up a orchestrator/transcoder
+## Step 3: Set up a orchestrator/transcoder
 
 `go run cmd/devtool/devtool.go setup transcoder`
 

diff --git a/doc/contributing.md → doc/go.md b/doc/contributing.md → doc/go.md
@@ -1,4 +1,4 @@
-# Contributing
+# Installing and Managing Go 
 
 ## Go
 
@@ -34,19 +34,3 @@ Then, you can run the following command which should download the arm64 binary i
 ```
 gvm install <version> -B
 ```
-
-## Changelog
-
-Every change (feature, bug fix, etc.) should be made in a PR that includes an update to the `CHANGELOG_PENDING.md` file which tracks the set of changes that will be included in the next release.
-
-Changelog entries should be formatted as follows:
-
-```
-- \#xxx Description of the change (@contributor)
-```
-
-`xxx` is the PR number (if for whatever reason a PR number cannot be used the issue number is acceptable) and `contributor` is the author of the change. The full link to the PR is not necessary because it will automatically be added when a release is created, but make sure to include the backslash and pound i.e. `\#2313`.
-
-Changelog entries should be classified based on the `livepeer` mode of operation that they pertain to i.e. General, Broadcaster, Orchestrator, Transcoder.
-
-Breaking changes should be documented in the "Breaking changes" section. Any changes that involve pending deprecations (i.e. a flag will be removed in the next release) should be documented in the "Upcoming changes" section.