From d68169757d5b9cd862dd7f79a62673272a5eda57 Mon Sep 17 00:00:00 2001 From: David Erwin Date: Tue, 27 Jun 2017 15:04:00 -0400 Subject: [PATCH 1/4] Rewrite contributor's guide --- CONTRIBUTING.md | 77 -------------------- docs/_data/sidebars/talk_sidebar.yml | 3 + docs/contributors-guide.md | 103 +++++++++++++++++++++++++++ 3 files changed, 106 insertions(+), 77 deletions(-) delete mode 100644 CONTRIBUTING.md create mode 100644 docs/contributors-guide.md diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md deleted file mode 100644 index 94e2be437..000000000 --- a/CONTRIBUTING.md +++ /dev/null @@ -1,77 +0,0 @@ -# Contributor's Guide - -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)! - -By contributing to this project you agree to the [Code of Conduct](https://coralproject.net/code-of-conduct.html). - -## Product Roadmap - -You can view what the Coral Team is working on next here https://www.pivotaltracker.com/n/projects/1863625. - -If you'd like to see our longer term roadmap, [get in touch.](https://coralproject.net/contact.html) - - -## 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 completeness 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 - -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) -* [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 - -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. - -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 [Slack channel](https://coralprojectslackin.herokuapp.com/), where you can talk directly with the Team and other community members, -* our [current stories](https://www.pivotaltracker.com/n/projects/1863625), and -* our [issues](https://github.com/coralproject/talk/issues). - - -Examples: - -* [Add An Emoji Button to Comments](https://github.com/coralproject/talk/wiki/Add-An-Emoji-Button-to-Comments) - - -### Work on the Core - -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 consider: - -* [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). diff --git a/docs/_data/sidebars/talk_sidebar.yml b/docs/_data/sidebars/talk_sidebar.yml index f0227274b..b44c9648f 100644 --- a/docs/_data/sidebars/talk_sidebar.yml +++ b/docs/_data/sidebars/talk_sidebar.yml @@ -11,6 +11,9 @@ entries: - title: About url: /index.html output: web + - title: Contribute + url: /contribute.html + output: web - title: FAQ url: /faq.html output: web diff --git a/docs/contributors-guide.md b/docs/contributors-guide.md new file mode 100644 index 000000000..bffc6f2dc --- /dev/null +++ b/docs/contributors-guide.md @@ -0,0 +1,103 @@ +--- +title: Contributor's Guide +keywords: homepage +sidebar: talk_sidebar +permalink: contributions.html +summary: +--- + + +Welcome! This guide is meant + +## What should I Contribute? + +There are three main ways to contribute to Talk: + +* Writing Code +* Writing Docs +* Participating in conversation +* Translating + +## Contributing Code + +The first question to ask is where your contribution fits into Talk's plugin / core architecture. + +Talk core consists of architecture and functionality that deliver stability, security, scalability, extendability and other *abilities. In addition, the Core contains features and functionality that is essential to the operation of Talk as a product. + +Talk plugins deliver the featuers and functionality that can be changed or removed. Much of the default functionality is delivered by plugins allowing developers to change behavior along product lines that we've found to be important. + +Our goal is to continually extend our plugin infrastructure making the Core as pluggable as possible. Ultimately, a day may come where the Core of Talk is simply a framework for delivering a certain flavor of web applications. + +### Should I contribute via a Plugin or to the Core? + +Ask these questions: + +1) Does Talk's exiting Plugin APIs support the thing you want to build? + +If so, then you should build it as a plugin. Feel free to explore here on your own or reach out to us. We love to advise on plugins, so please feel free to _specify your contribution_ as described below to start a conversation. We will help you conceptualize, architect and promote your plugin if it is in line with our values. + +2) If the current Plugin API doesn't support your idea, should the API be extended to do so? + +As mentioned above, we seek to interatively extend the Talk Plugin API. How do we know what the next iteration will be? Your ideas. If you want to build a plugin that isn't supported, please _specify your contribution_ as described below and we will discuss how the Core may be extended to support not only your specific idea, but other's ideas as well. + +Quite often the only things missing from Core are things like _events_, _slots_, _CSS classes_, etc... Adding these is a great way to become a Core Contibutor and break new ground as a Plugin Developer. + +3) Is my idea really just Core? + +Amazing! We are always looking to extend the capabilities of Talk. We look forward to discussing what you've got to bring! + + +### Specify your Contribution + +Coral has adopted an iterative, agile development philosophy. All contributions that make it into the Talk repo should start with a story or this form: + +`As a [type of person] I'd like to be able to [do something] so that I can [get some result].` + +We have found that the exercise of expressing our next steps in this format allows us to ground our technical choices in a clear, simple product need. It also expresses that product need in a way that doesn't imply a specific technical solution allowing for debate as to the best way to solve the problem. + + +## Contributing Documentation + +Clear docs are a prerequisite for a successful open source project. Contributing to the documentation is often more important than contributing to the code! + +We are looking for _documentarians_ to: + +* make clarity, grammar and completeness updates, +* create new / missing sections, and +* take the lead in making sections, or the over all structure better. + +Information about how to update docs can be found in our [FAQ](faq.html#how-do-i-contribute-to-these-docs). + +If you'd like to make a significant contribution, please [file an issue](https://github.com/coralproject/talk/issues) describing the changes you would like to make and we'll begin the conversation. + +## Contributing Translations + +Talk's tranlations are stored in `.yml` files [here](https://github.com/coralproject/talk/tree/master/locales). + +Translations can be submitted via pull request. If you do not use github, you can use 'en.yml' as a template and email the translations to us and we can import it into the repo. + +## I want to contribute but I'm not sure what to do! + +If you want to contribute but don't have a clear idea of exactly what that may be, here are some resources that may help: + +### Product Roadmap + +Please visit our product roadmap here: https://www.pivotaltracker.com/n/projects/1863625. If you'd like to take on any of our scheduled tasks we'd be forever grateful! + +### Discussion Forum + +If you'd like to discuss what we're up to, please visit or [community](https://community.coralproject.net/) or [contact us](https://coralproject.net/contact.html). + +### Integrations + +Have a favorite analytics engine? Data science service? CMS? Auth platform? Deployment platform or pipeline? Pet project? Consider building a plugin to integrate them! + +### Favorite Features? + +Do you have a favorite feature of an exisitng platform that's not yet been done in Talk? Sounds like Talk needs that feature. + +## Thanks! + +By contributing to this project you agree to the [Code of Conduct](https://coralproject.net/code-of-conduct.html). + + From 3695ce5cb71d35cf771647e583039e31b439a404 Mon Sep 17 00:00:00 2001 From: David Erwin Date: Tue, 27 Jun 2017 15:08:21 -0400 Subject: [PATCH 2/4] Update links --- docs/contributors-guide.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/docs/contributors-guide.md b/docs/contributors-guide.md index bffc6f2dc..7b4fe4562 100644 --- a/docs/contributors-guide.md +++ b/docs/contributors-guide.md @@ -2,7 +2,7 @@ title: Contributor's Guide keywords: homepage sidebar: talk_sidebar -permalink: contributions.html +permalink: contribute.html summary: --- @@ -74,7 +74,7 @@ If you'd like to make a significant contribution, please [file an issue](https:/ Talk's tranlations are stored in `.yml` files [here](https://github.com/coralproject/talk/tree/master/locales). -Translations can be submitted via pull request. If you do not use github, you can use 'en.yml' as a template and email the translations to us and we can import it into the repo. +Translations can be submitted via pull request. localIf you do not use github, you can use 'en.yml' as a template and email the translations to us and we can import it into the repo. ## I want to contribute but I'm not sure what to do! From 2f0628143961a6bf7364d5bbb766f24aa67a5124 Mon Sep 17 00:00:00 2001 From: David Erwin Date: Mon, 3 Jul 2017 10:03:51 -0400 Subject: [PATCH 3/4] Move contributor's guide --- CONTRIBUTING.md | 89 +++++++++++++++++++++++++++++++++++ docs/contributors-guide.md | 96 +------------------------------------- 2 files changed, 90 insertions(+), 95 deletions(-) create mode 100644 CONTRIBUTING.md diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md new file mode 100644 index 000000000..3b316dbce --- /dev/null +++ b/CONTRIBUTING.md @@ -0,0 +1,89 @@ +# Contributor's Guide + +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)! + +By contributing to this project you agree to the [Code of Conduct](https://coralproject.net/code-of-conduct.html). + +## What should I Contribute? + +There are four main ways to contribute to Talk: + +* Writing Code +* Writing Docs +* Participating in conversation +* Providing Translations + +## Contributing Code + +### Create an Issue + +Conversation surrounding contributions begins in [issues](https://github.com/coralproject/talk/issues). + +#### When should I file? + +File early, preferably before beginning any programming in earnest. + +Please file issues if: + +* you would like to contribute to Talk Core. +* you are building a Plugin that the current Plugin API doesn't support. +* you are building a Plugin and want advice + +#### What should I include? + +Coral has adopted an iterative, agile development philosophy. All contributions that make it into the Talk repo should start with a story or this form: + +`As a [type of person] I'd like to be able to [do something] so that I can [get some result].` + +This exercise does two things: + +* allows us to ground our technical choices in a clear, simple product need. +* expresses that product need in a way that doesn't imply a specific technical solution allowing for debate as to the best way to solve the problem. + +Please feel free to provide as much detail as possible when filing the issue but please do keep the initial issue specific to one need and try to avoid including technical or design solutions. + +If you have a specific technical or design solution in mind, please submit it as the first comment on the thread. + +## Contributing Documentation + +Clear docs are a prerequisite for a successful open source project. Contributing to the documentation is often more important than contributing to the code! + +We are looking for _documentarians_ to: + +* make clarity, grammar and completeness updates, +* create new / missing sections, and +* take the lead in making sections, or the over all structure better. + +Information about how to update docs can be found in our [FAQ](faq.html#how-do-i-contribute-to-these-docs). + +If you'd like to discuss a contribution, please [file an issue](https://github.com/coralproject/talk/issues) describing the changes you would like to see. + +## Contributing Translations + +Talk's tranlations are stored in `.yml` files [here](https://github.com/coralproject/talk/tree/master/locales). + +Translations can be submitted via pull request. If you do not use github, you can use 'en.yml' as a template and [email](https://coralproject.net/contact.html) the translations to us. We can import it into the repo. + +## I want to contribute but I'm not sure what to do! + +If you want to contribute but don't have a clear idea of exactly what that may be, here are some resources that may help: + +### Product Roadmap + +Please visit our product roadmap here: https://www.pivotaltracker.com/n/projects/1863625. If you'd like to take on any of our scheduled tasks we'd be forever grateful! + +### Discussion Forum + +If you'd like to discuss what we're up to, please visit or [community](https://community.coralproject.net/) or [contact us](https://coralproject.net/contact.html). + +### Integrations + +Have a favorite analytics engine? Data science service? CMS? Auth platform? Deployment platform or pipeline? Pet project? Consider building a plugin to integrate them! + +### Favorite Features? + +Do you have a favorite feature of an existing platform that's not yet been done in Talk? Sounds like Talk needs that feature. + +## Thanks! diff --git a/docs/contributors-guide.md b/docs/contributors-guide.md index 7b4fe4562..792055772 100644 --- a/docs/contributors-guide.md +++ b/docs/contributors-guide.md @@ -6,98 +6,4 @@ permalink: contribute.html summary: --- - -Welcome! This guide is meant - -## What should I Contribute? - -There are three main ways to contribute to Talk: - -* Writing Code -* Writing Docs -* Participating in conversation -* Translating - -## Contributing Code - -The first question to ask is where your contribution fits into Talk's plugin / core architecture. - -Talk core consists of architecture and functionality that deliver stability, security, scalability, extendability and other *abilities. In addition, the Core contains features and functionality that is essential to the operation of Talk as a product. - -Talk plugins deliver the featuers and functionality that can be changed or removed. Much of the default functionality is delivered by plugins allowing developers to change behavior along product lines that we've found to be important. - -Our goal is to continually extend our plugin infrastructure making the Core as pluggable as possible. Ultimately, a day may come where the Core of Talk is simply a framework for delivering a certain flavor of web applications. - -### Should I contribute via a Plugin or to the Core? - -Ask these questions: - -1) Does Talk's exiting Plugin APIs support the thing you want to build? - -If so, then you should build it as a plugin. Feel free to explore here on your own or reach out to us. We love to advise on plugins, so please feel free to _specify your contribution_ as described below to start a conversation. We will help you conceptualize, architect and promote your plugin if it is in line with our values. - -2) If the current Plugin API doesn't support your idea, should the API be extended to do so? - -As mentioned above, we seek to interatively extend the Talk Plugin API. How do we know what the next iteration will be? Your ideas. If you want to build a plugin that isn't supported, please _specify your contribution_ as described below and we will discuss how the Core may be extended to support not only your specific idea, but other's ideas as well. - -Quite often the only things missing from Core are things like _events_, _slots_, _CSS classes_, etc... Adding these is a great way to become a Core Contibutor and break new ground as a Plugin Developer. - -3) Is my idea really just Core? - -Amazing! We are always looking to extend the capabilities of Talk. We look forward to discussing what you've got to bring! - - -### Specify your Contribution - -Coral has adopted an iterative, agile development philosophy. All contributions that make it into the Talk repo should start with a story or this form: - -`As a [type of person] I'd like to be able to [do something] so that I can [get some result].` - -We have found that the exercise of expressing our next steps in this format allows us to ground our technical choices in a clear, simple product need. It also expresses that product need in a way that doesn't imply a specific technical solution allowing for debate as to the best way to solve the problem. - - -## Contributing Documentation - -Clear docs are a prerequisite for a successful open source project. Contributing to the documentation is often more important than contributing to the code! - -We are looking for _documentarians_ to: - -* make clarity, grammar and completeness updates, -* create new / missing sections, and -* take the lead in making sections, or the over all structure better. - -Information about how to update docs can be found in our [FAQ](faq.html#how-do-i-contribute-to-these-docs). - -If you'd like to make a significant contribution, please [file an issue](https://github.com/coralproject/talk/issues) describing the changes you would like to make and we'll begin the conversation. - -## Contributing Translations - -Talk's tranlations are stored in `.yml` files [here](https://github.com/coralproject/talk/tree/master/locales). - -Translations can be submitted via pull request. localIf you do not use github, you can use 'en.yml' as a template and email the translations to us and we can import it into the repo. - -## I want to contribute but I'm not sure what to do! - -If you want to contribute but don't have a clear idea of exactly what that may be, here are some resources that may help: - -### Product Roadmap - -Please visit our product roadmap here: https://www.pivotaltracker.com/n/projects/1863625. If you'd like to take on any of our scheduled tasks we'd be forever grateful! - -### Discussion Forum - -If you'd like to discuss what we're up to, please visit or [community](https://community.coralproject.net/) or [contact us](https://coralproject.net/contact.html). - -### Integrations - -Have a favorite analytics engine? Data science service? CMS? Auth platform? Deployment platform or pipeline? Pet project? Consider building a plugin to integrate them! - -### Favorite Features? - -Do you have a favorite feature of an exisitng platform that's not yet been done in Talk? Sounds like Talk needs that feature. - -## Thanks! - -By contributing to this project you agree to the [Code of Conduct](https://coralproject.net/code-of-conduct.html). - - +Our Contributor's Guide can be found [here](https://github.com/coralproject/talk/blob/master/CONTRIBUTING.md). From a50b39091fe8ddf597c2d92937095ae246f8c263 Mon Sep 17 00:00:00 2001 From: David Erwin Date: Mon, 3 Jul 2017 10:13:09 -0400 Subject: [PATCH 4/4] ABC Always Be Clarifying --- CONTRIBUTING.md | 15 ++++++--------- 1 file changed, 6 insertions(+), 9 deletions(-) diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index 3b316dbce..140105723 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -8,30 +8,27 @@ By contributing to this project you agree to the [Code of Conduct](https://coral ## What should I Contribute? -There are four main ways to contribute to Talk: +There are at least three ways to contribute to Talk: * Writing Code * Writing Docs -* Participating in conversation * Providing Translations -## Contributing Code - -### Create an Issue +## Writing Code Conversation surrounding contributions begins in [issues](https://github.com/coralproject/talk/issues). -#### When should I file? +### When should I Create an Issue? -File early, preferably before beginning any programming in earnest. +File an issue as soon as you have an idea of something you'd like to contribute. We would love to hear what you're thinking and help refine the idea to make it into the Talk ecosystem. Please file issues if: * you would like to contribute to Talk Core. * you are building a Plugin that the current Plugin API doesn't support. -* you are building a Plugin and want advice +* you are building a Plugin and want advice. -#### What should I include? +### What should I include? Coral has adopted an iterative, agile development philosophy. All contributions that make it into the Talk repo should start with a story or this form: