From ef40cf37fe943824c23fc35171f06e4d3c824421 Mon Sep 17 00:00:00 2001 From: David Erwin Date: Tue, 27 Dec 2016 10:55:16 -0500 Subject: [PATCH 1/4] Update contribution guide --- CONTRIBUTING.md | 139 +++++++++++++++++++----------------------------- 1 file changed, 56 insertions(+), 83 deletions(-) diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index 9fa7985c0..8089822c5 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -1,95 +1,68 @@ -# Contribution Guide +# Contributor's Guide -We're very excited that you're interested in contributing to Talk! There is much to do. Before you begin, please review this document to get a sense of the practices and philosophies that hold this project together. +Welcome! We are very excited that you are interested in contributing to Talk. + +This document is a companion to help you approach contributing. If it does not do so, please [let us know how we can improve it](https://github.com/coralproject/talk/issues)! + +What would you like to do? + +## Contribute to the documentation +Clear docs are a prerequisite for a successful open source project. We value non-code and code contributions equally. + +We are looking for _documentarians_ to: + +* make clarity, grammar and completenes updates, +* create new / missing sections, and +* take the lead in making sections, or the over all structure better. + +### But how? + +* Our public docs site can be updated [here](https://github.com/coralproject/docs). +* [Let us know](https://github.com/coralproject/talk/wiki/Contact-Us) if you'd like permission to update our wiki. +* Update any of our .md docs files by following [this guide](https://github.com/coralproject/talk/wiki/Forking,-Branching-and-Merging). +* Our API docs need to be kept honest. [Update them here](https://github.com/coralproject/talk/blob/master/docs/swagger.yaml). + +## Integrate into your environment + +Talk is designed to integrate into existing environments in a variety of ways: + +* [Auth integrations](https://github.com/coralproject/talk/wiki/Security#authentication-strategies) +* [Push assets into Talk](https://github.com/coralproject/talk/blob/master/routes/api/assets/index.js) +* Monitoring Hooks (coming in 2017) + +If you're considering deploying Talk, [please let us know](https://github.com/coralproject/talk/wiki/Contact-Us)! We are quite literally doing this for you and want to help you succeed any way we can. + +If you are writing custom integration code in your fork of Talk, please consider keeping it generic and filing a Pull Request to contribute it back to the project! See our [forking and merging guidelines](https://github.com/coralproject/talk/wiki/Forking,-Branching-and-Merging) for more info. + +## Write some code + +### Build a New Feature / Plugin + +Talk is beginning life as a Commenting Platform, but is architected to support many varieties of community engagement. + +Please [contact us](https://github.com/coralproject/talk/wiki/Contact-Us) early and often if you'd like to help. We would love to hear your ideas for features and plugins and help you find a way to productively engage the project. + +To get an idea of where the Coral Team is going, see: + +* our [product/design Trello board](https://trello.com/b/ILND751a/talk), +* our [current stories](https://www.pivotaltracker.com/n/projects/1863625), and +* our [issues](https://github.com/coralproject/talk/issues). -## Doing the Work +Examples: -We are here to make it as seamless as possible to contribute to Talk. The following lists are meant to make it straightforward to perform the mechanics of working on the project so you can focus your energy toward writing and reviewing content. +* [Add An Emoji Button to Comments](https://github.com/coralproject/talk/wiki/Add-An-Emoji-Button-to-Comments) -### Code Reviews +### Work on the Core -One of the most valuable aspects of working in software. It is something that should challenge the reviewer and author alike. It is a way of focusing knowledge, experience and opinions for the benefit of the project and the participants. +There is always more work to be done to make an application more stable, scaleable and secure. -Code reviews are a collaboration to make _the work_ as good as it can be. Code reviews are not a good venue for providing direct instruction to _the author._ Focus on positive, incremental improvements that can be made on the work at hand. +If you see issues in the code or have ideas on how we may improve Talk, please conisder: -Please take your time when writing and reviewing code. Here are some fundamental questions to open up a reviewing headspace. - -**Is the code clear, efficient and a pleasure to read?** - -Somewhere at the intersection of good variable names, well laid out file structures, consistent formatting and appropriate comments lies beautiful code. Code is language spoken to at least two very distinct audiences, the computer that interprets it and the developer who encounters it. Both should be at the front of your mind when reviewing code. - -Thinking like a computer, you could ask: - -* Is the code using memory efficiently? -* Is data being moved around unnecessarily? -* Are multiple network requests being made where fewer would do? -* Is there excess processing happening in a synchronous flow that may disrupt user experience? -* Are there large libraries included for small gains? - -Then, returning to your human roots... Is the code readable? - -* Can I understand what is happening here (and maybe even why) by simply opening up the file, starting at the top and reading downward? -* Do comments convey clear, full thoughts in a narrative language that provides background for the code choices? -* Are the files separated logically such that each one contains a clear concept of code? +* [contributing a fix](https://github.com/coralproject/talk/wiki/Forking,-Branching-and-Merging), +* [filing an issue](https://github.com/coralproject/talk/issues), or +* or otherwise [letting us know](https://github.com/coralproject/talk/wiki/Contact-Us). -**Is the API documentation up to date? Are all client calls written against the docs?** -We use [swagger](https://github.com/coralproject/talk/blob/master/swagger.yaml) to track our API documentation. - -* If APIs are created or updated, is the swagger.yml file up to date? There's nothing more frustrating than trying to develop against docs that are out of date or wrong. We need to be meticulous here as it's the little differences that can cause the most frustration and tricky bugs. -* If client code calls APIs, are they written against the swagger.yml file? Are all return codes handled? - -**Is there sufficient test coverage?** - -Our tests folder is set up to mirror the code folders: [https://github.com/coralproject/talk/tree/master/tests](https://github.com/coralproject/talk/tree/master/tests) - -* Can you a sense of the logic behind the code by reading the tests? -* Can you see both what should happen and what should _never, ever_ be allowed to happen? -* Are there future cases that are guarded against via the creation of unit tests (aka, making sure things are typed, specifically checking for all values that will be used, etc...)? - - -### Forking, Branching and Merging - -Talk follows the _master as tip_ repo structure. `master` is the bleeding edge. It should be _as stable as possible_ but may suffer instabilities, generally during times that fundamental architectural elements are added. - -Releases are _tagged_ off the master branch. - -Contributions to Talk follow this process. There are a lot of steps, but mechanically following these steps will standardize communication, help stop errors and let you focus on your contribution. - -* At the outset of a piece of work, a branch or fork is made from master. -* The work is done in that fork. -* As soon as the work has taken shape, a PR is created for discussion. (If the PR is created for review before it's ready to merge, please make that clear in the description/title.) -* At least one other contributor to the project must review all code (see Code Reviews below.) -* If there are merge conflicts with master, merge master into the branch. -* Ensure that [circleci](https://circleci.com/) passes all tests for your branch. (If you have forked and do not have circleci set up, you and the reviewer should independently ensure that all the of Continuous Integration steps pass before merging.) -* If merge conflicts exist with `master`, merge `master` into your branch and re-run CI before merging into master. -* Merge to master, but _you're not quite done yet!_ -* Deploy master to staging (or have a core member do so.) -* Ensure that all your changes are working on staging. -* Have your reviewer verify the same. -* ... aaaand the work is delivered! - - -## Continuous Integration - -We use circleci to run our ci: [https://circleci.com/gh/coralproject/talk](https://circleci.com/gh/coralproject/talk) - -Our pipeline will _test_, _lint_, and _build_ all pushes to the repo. - -Any branch not passing CI will not be merged into master. - -If you're working in a fork, please run each of the steps locally before submitting a PR. - - -## Coding Style - -### API Design - -When building APIs, we follow these principles: - -* Follow [RESTful](https://en.wikipedia.org/wiki/Representational_state_transfer) principles for basic operations. -* Avoid routing yourself into a corner, for example, by putting a variable other than an object's id directly after an object. -* Put non-required, flexible variables into query params, required/identity based values in request params. From 0219f1916e9a4db0961fa6ae5b8cf1c6b9287401 Mon Sep 17 00:00:00 2001 From: David Erwin Date: Tue, 27 Dec 2016 10:59:08 -0500 Subject: [PATCH 2/4] Link contributing.md from readme.md --- CONTRIBUTING.md | 8 +++++++- README.md | 6 +----- 2 files changed, 8 insertions(+), 6 deletions(-) diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index 8089822c5..3e4bfbb56 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -4,7 +4,13 @@ Welcome! We are very excited that you are interested in contributing to Talk. This document is a companion to help you approach contributing. If it does not do so, please [let us know how we can improve it](https://github.com/coralproject/talk/issues)! -What would you like to do? + +## Product Roadmap + +You can view what the Coral Team is working on next here https://www.pivotaltracker.com/n/projects/1863625. + +You can view product ideas and our longer term roadmap here https://trello.com/b/ILND751a/talk. + ## Contribute to the documentation Clear docs are a prerequisite for a successful open source project. We value non-code and code contributions equally. diff --git a/README.md b/README.md index 3b258736f..cfa8bea95 100644 --- a/README.md +++ b/README.md @@ -4,11 +4,7 @@ A commenting platform from [The Coral Project](https://coralproject.net). ## Contributing to Talk -### Product Roadmap - -You can view what the Coral Team is working on next here https://www.pivotaltracker.com/n/projects/1863625. - -You can view product ideas and our longer term roadmap here https://trello.com/b/ILND751a/talk. +See our [Contribution Guide](https://github.com/coralproject/talk/blob/master/CONTRIBUTING.md)! ## Usage From c86148c0f10eb098165346f8cd192243620ef5ac Mon Sep 17 00:00:00 2001 From: David Erwin Date: Tue, 27 Dec 2016 11:39:54 -0500 Subject: [PATCH 3/4] Add links to INSTALL.md --- CONTRIBUTING.md | 4 ++++ README.md | 7 +++++++ 2 files changed, 11 insertions(+) diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index 3e4bfbb56..69765d662 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -30,6 +30,8 @@ We are looking for _documentarians_ to: ## Integrate into your environment +First, [set up a dev environment](https://github.com/coralproject/talk/blob/master/INSTALL.md). Please let us know how this goes! + Talk is designed to integrate into existing environments in a variety of ways: * [Auth integrations](https://github.com/coralproject/talk/wiki/Security#authentication-strategies) @@ -42,6 +44,8 @@ If you are writing custom integration code in your fork of Talk, please consider ## Write some code +First, [set up a dev environment](https://github.com/coralproject/talk/blob/master/INSTALL.md). Please let us know how this goes! + ### Build a New Feature / Plugin Talk is beginning life as a Commenting Platform, but is architected to support many varieties of community engagement. diff --git a/README.md b/README.md index cfa8bea95..6c331c115 100644 --- a/README.md +++ b/README.md @@ -8,6 +8,13 @@ See our [Contribution Guide](https://github.com/coralproject/talk/blob/master/CO ## Usage +### Installation + +To set up a development environment or build from source, see [INSTALL.md](https://github.com/coralproject/talk/blob/master/INSTALL.md). + +To launch a Talk server of your own from your browser without any need to muck about in a terminal or think about engineering concepts, stay tuned. We will launch [our installer](https://github.com/coralproject/talk-install) shortly!! + + ### Configuration The Talk application requires specific configuration options to be available From 9a608fd02e519ac475e5a80ea5da2bf49c90bffe Mon Sep 17 00:00:00 2001 From: David Erwin Date: Tue, 27 Dec 2016 11:50:34 -0500 Subject: [PATCH 4/4] Spell stuff right and clean up --- CONTRIBUTING.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index 69765d662..66ae8ade8 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -17,7 +17,7 @@ Clear docs are a prerequisite for a successful open source project. We value non We are looking for _documentarians_ to: -* make clarity, grammar and completenes updates, +* make clarity, grammar and completeness updates, * create new / missing sections, and * take the lead in making sections, or the over all structure better. @@ -68,7 +68,7 @@ Examples: There is always more work to be done to make an application more stable, scaleable and secure. -If you see issues in the code or have ideas on how we may improve Talk, please conisder: +If you see issues in the code or have ideas on how we may improve Talk, please consider: * [contributing a fix](https://github.com/coralproject/talk/wiki/Forking,-Branching-and-Merging), * [filing an issue](https://github.com/coralproject/talk/issues), or