docs: add code of conduct and contributing documentation #671

zacharygolba · 2017-01-28T23:16:12Z

This PR aims to make contributing to Lux less vague and improve the overall sense of community around Lux.

The Lux Code of Conduct

This document outlines our expectations for participants within the Lux community, as well as steps to reporting unacceptable behavior.

Contributing to Lux

This document explains how to be an effective participant in the Lux community. In this document you can expect to find answers to high level questions such as how to report a bug or request feature. Also, you can find information for some lower level topics such as how to set up a local development environment and the process of submitting a pull request.

Support Materials

Issue Template - A template that makes it easier for members of the community to provide helpful information when reporting a bug.
RFC Repository - A repository that will contain a formally documented RFC process as well as *accepted RFCs.

* RFCs will be submitted in the form of a pull request to the postlight/lux-rfcs repository. Once an RFC has been accepted, it will be merged into the master branch. If an RFC has been merged to master, a member of the community can implement it in Lux core.

To Do

Pre Merge

Create a pull request template.

Post Merge

Document the RFC process in the postlight/lux-rfcs repository.

Questions

Here are a few questions that came up when writing the documents in this pull request. This list is not exhaustive. This pull request itself is asking the question, "what policies should we have and what should these document contain?".

~~Should the language in the Code of Conduct be generalized for all open-source projects at Postlight?~~
~~Does the Postlight Charter fit into the Code of Conduct? If so, what parts?~~
~~When should the document speak from the perspective of Postlight/Postlight Labs vs the Lux Community?~~
~~Is lux@postlight.com the appropriate contact address to list in the Code of Conduct?~~
~~Is sending an email to lux@postlight.com the appropriate contact method to report violations of the Code of Conduct?~~

Acknowledgement

A lot of what you will find has been adapted from documents of the Node.js Foundation and Rust Community. I found this to be the easiest way to begin to form the blueprint for documentation and policies of our own. In the event that the unoriginal content is cited in an unethical way, leave a comment in the source view and it will be corrected.

Closes #51

codecov-io · 2017-01-28T23:28:44Z

Codecov Report

Merging #671 into master will not change coverage.
The diff coverage is n/a.

@@           Coverage Diff           @@
##           master     #671   +/-   ##
=======================================
  Coverage   92.38%   92.38%           
=======================================
  Files         180      180           
  Lines        1996     1996           
=======================================
  Hits         1844     1844           
  Misses        152      152

Continue to review full report at Codecov.

Legend - Click here to learn more
Δ = absolute <relative> (impact), ø = not affected, ? = missing data
Powered by Codecov. Last update 61bb4f4...ddcc48a. Read the comment docs.

fix: duplicate source materials entry in contributing.md docs: add preliminary content to code of conduct dx: add .nvmrc file (#672) docs: add build and test steps to contributing.md docs: add issue template docs: fix linter error for issue template docs: add docs for making documentation contributions docs: add link to rfcs repository in contributing.md docs: update readme and remove roadmap in favor of lux-rfcs repo style: whitespace change in contributing.md docs: left align column 2 of the commit style table in contributing.md docs: missing punctuation in code of conduct dx: add .nvmrc file (#672) docs: change irc to gitter in code of conduct

ginatrapani

My two cents on the open questions:

Should the language in the Code of Conduct be generalized for all open-source projects at Postlight?

Eventually yes, but doing it now is probably a premature optimization. The CoC is an evolving document that we will iterate on to meet community needs as it grows -- maybe we can add language about the fact that it will change over time, and when the next Postlight OSS project needs a CoC we can start from here.

Does the Postlight Charter fit into the Code of Conduct? If so, what parts?

Yes -- off the top, the part about inclusivity for sure, probably some others as well. Once the charter is published, at that point we could add language to the CoC about how Postlight Labs maintains Lux, and here are how Postlight's values are reflected within Lux's CoC.

When should the document speak from the perspective of Postlight/Postlight Labs vs the Lux Community?

Always default to the Lux Community, and refer to Postlight Labs as the project maintainers.

Is lux@postlight.com the appropriate contact address to list in the Code of Conduct?

Maybe lux+moderators@postlight.com? Then we could use the plus notation to accept email about different issues to the same inbox (ie, security, moderation, anything else that comes up).

Is sending an email to lux@postlight.com the appropriate contact method to report violations of the Code of Conduct?

Would go with lux+moderators@postlight.com here, too.

ginatrapani · 2017-01-30T23:16:37Z

CODE_OF_CONDUCT.md

+
+**Contact**: [lux@postlight.com](mailto:lux@postlight.com)
+
+*   We are committed to providing a friendly, safe and welcoming environment for


"The Lux community is committed" ("we" a bit unspecific)

ginatrapani · 2017-01-30T23:17:27Z

CODE_OF_CONDUCT.md

+
+## Conduct
+
+**Contact**: [lux@postlight.com](mailto:lux@postlight.com)


"Contact Lux moderators:" ?

ginatrapani · 2017-01-30T23:22:16Z

CODE_OF_CONDUCT.md

+sexual orientation, disability, personal appearance, body size, race, ethnicity,
+age, religion, nationality, or other similar characteristic.
+
+*   On Gitter, please avoid using overtly sexual nicknames or other nicknames


Suggestion: "avoid using racist, sexually explicit or otherwise hostile nicknames that might detract from a friendly, safe and welcoming environment for all."

Great suggestion! I'll make the change.

ginatrapani · 2017-01-30T23:23:51Z

CODE_OF_CONDUCT.md

+others.
+
+In the Lux community we strive to go the extra step to look out for each other.
+Don't just aim to be technically unimpeachable, try to be your best self. In


I love this line

I agree. This is one of my favorite parts of the Rust CoC.

ginatrapani · 2017-01-30T23:24:26Z

CODE_OF_CONDUCT.md

+they're off-topic; this all too often leads to unnecessary fights, hurt feelings,
+and damaged trust; worse, it can drive people away from the community entirely.
+
+And if someone takes issue with something you said or did, resist the urge to be


Drop the opening And on this sentence.

ginatrapani · 2017-01-30T23:28:42Z

CONTRIBUTING.md

+always work, and sometimes it's hard to know what to search for, so consider
+this extra credit. We won't mind if you accidentally file a duplicate report.
+
+Opening an issue is as easy as following [this link](https://github.com/postlight/lux/issues/new)


Is there a different process for reporting a security vulnerability that we would not want documented publicly? Perhaps a lux+security@postlight.com email for sensitive security issues? This is what we did at ThinkUp: http://thinkup.readthedocs.io/en/latest/install/security.html#how-to-report-a-security-bug

This is a great suggestion. I included an adapted version of the language in the ThinkUp docs in CONTRIBUTING.md. I also added ThinkUp Security and Data Privacy to the acknowledgements at the bottom of the document.

ginatrapani · 2017-01-30T23:35:17Z

CONTRIBUTING.md

+Want to make a change to Lux? Submit a pull request! We use the "fork and pull"
+model [described here](https://help.github.com/articles/creating-a-pull-request-from-a-fork).
+
+**Before submitting a pull request**, please make sure you do the following:


Can remove everything after "make sure:" here or you could do "make sure you have:" and delete "You have" from the start of each bullet.

ginatrapani · 2017-01-30T23:35:32Z

CONTRIBUTING.md

+that you may have changed.
+*   [X] You have no linter errors to correct after running `npm run lint`.
+*   [X] You have no type errors to correct after running `npm run flow`.
+*   [X] You have ran the test suite via `npm test` and it passed.


Typo: run not ran

ginatrapani · 2017-01-31T02:27:01Z

CONTRIBUTING.md

+
+If you have never written JavaScript with [Flow](https://flowtype.org) or
+[TypeScript](https://www.typescriptlang.org/) before, you may have a bit of a
+learning curve. If you get stuck on something, feel free to ask a question in the


Can we suggest any starter resources here to get up to speed with Flow/Typescript? I really like how we're suggesting editor plugins below.

This is a great idea! I added a link to the Flow documentation at the bottom of this section.

ginatrapani · 2017-01-31T02:33:18Z

CONTRIBUTING.md

+in community.*
+
+## Contents
+


Suggestion: include a definition of what we consider a contribution to Lux, a broad definition. Code for sure--and most of this document will address that type of contribution--but also: updating and writing documentation, answering questions and chatting with the community in the Gitter room, filing, organizing, commenting on issues, teaching others how to use Lux, making suggestions on branding, building community, outreach, etc. I think one of the most common mistakes OSS projects make is focusing on code when so much more goes into writing software as a community.

I couldn't agree more! I'll get something basic written up and check in with you once it's pushed.

I have added a Ways to Contribute section. I had a tough time wording it for some reason. For the sake of tone, I tried to express that the list is not exhaustive without directly saying it. I'm not sure that came across correctly. Suggestions/feedback would be appreciated. 😃

The new section looks great. Related, this is pretty interesting: https://github.com/kentcdodds/all-contributors

Thank you! Great idea!

…into docs-contributing

docs: copy changes in code of conduct

nickschot

Looks great overall!

Small suggestion and typo fix.

nickschot · 2017-02-08T16:19:24Z

CONTRIBUTING.md

+*   [flow-for-vscode (Visual Studio Code)](https://github.com/flowtype/flow-for-vscode)
+*   [flow-for-emacs (Emacs)](https://github.com/flowtype/flow-for-emacs)
+*   [vim-flow (Vim)](https://github.com/flowtype/vim-flow)
+


Maybe add WebStorm too? I feel that with that one included you've covered the most popular text-editors/IDE's. Unfortunately the link is version specific (though official flow support has only been added in that (the most recent) version).

Link: https://www.jetbrains.com/help/webstorm/2016.3/using-the-flow-type-checker.html

nickschot · 2017-02-08T16:21:59Z

CONTRIBUTING.md

+If you use [nvm](https://github.com/creationix/nvm) to manage Node.js versions
+and zsh (like [Oh-My-ZSH](https://github.com/robbyrussell/oh-my-zsh)), you can
+have nvm switch to the correct Node.js version automatically when you cd into
+this repository. To do so, add the following to your `~/.zshrc` file:


Great tip/script!

Thanks! This has been a life saver for me. 😃

nickschot · 2017-02-08T16:23:47Z

CONTRIBUTING.md

+## Writing Documentation
+
+Improvements to documentation are a great way to start contributing to Lux. The
+sources for the official documentation is generated from source code comments


The sources for the official documentation is are generated from source code comments

jamemackson

Generally I think this all looks good :) I added a few thoughts, all relatively minor things...

jamemackson · 2017-02-08T18:40:42Z

CODE_OF_CONDUCT.md

+sexual orientation, disability, personal appearance, body size, race, ethnicity,
+age, religion, nationality, or other similar characteristic.
+
+*   On Gitter, please avoid avoid using racist, sexually explicit or otherwise


why limit this to just on gitter? these seem like good rules of the road generally speaking.

Couldn't agree more! 😃

jamemackson · 2017-02-08T19:17:37Z

CONTRIBUTING.md

+#### JavaScript
+
+We use a slightly modified version of the Airbnb JavaScript [Style Guide](https://github.com/airbnb/javascript).
+To enforce this, all pull requests that must pass [ESLint](http://eslint.org/)


I think we have an unneeded 'that' in this sentence.

Good catch!

jamemackson · 2017-02-09T16:45:47Z

CONTRIBUTING.md

+*   [X] You have no linter errors to correct after running `npm run lint`.
+*   [X] You have no type errors to correct after running `npm run flow`.
+*   [X] You have run the test suite via `npm test` and it passed.
+


Some mention here about lux's opinion about squashing commits seems warranted to me also.

This is a good point. I'm not sure that we have to explicitly mention it since GitHub introduced the squash and merge button. I'm open to discussing this more.

If that button works, I'd say it isn't an issue. You'll have to press to merge anyway.

Good point. @nickschot

zacharygolba · 2017-03-20T16:19:04Z

@nickschot I have updated this PR based on you comments. Whenever you have a moment and this looks good to you, can you update your "approval status"? 😃

* docs: add code of conduct and contributing documentation fix: duplicate source materials entry in contributing.md docs: add preliminary content to code of conduct dx: add .nvmrc file (#672) docs: add build and test steps to contributing.md docs: add issue template docs: fix linter error for issue template docs: add docs for making documentation contributions docs: add link to rfcs repository in contributing.md docs: update readme and remove roadmap in favor of lux-rfcs repo style: whitespace change in contributing.md docs: left align column 2 of the commit style table in contributing.md docs: missing punctuation in code of conduct dx: add .nvmrc file (#672) docs: change irc to gitter in code of conduct * docs: use lux+moderators@postlight.com instead of lux@postlight.com * docs: copy changes in code of conduct docs: copy changes in code of conduct * docs: typo in contribting.md * docs: copy changes in contributing.md * docs: add instructions for reporting security vulnerabilities * docs: add a link to flow documentation in contributing.md * docs: typo in contributing.md * docs: add webstorm flow docs to contributing.md * docs: remove unecessary "that" in contributing.md * docs: widen the scope of the second bullet in the code of conduct * docs: add pull request template * docs: add "ways to contribute" section to contributing.md

* refactor: use jest instead of mocha + chai * feat: add http and mock adapters * tests: updated failing test suites * fix: continued updates to unit tests * refactor: more test updates * refactor: more test updates * refactor: more test updates * feat: use jest-junit reporter * fix: attempt to set node_env in child processes * test: set node_env in circle.yml * fix: update junit output * refactor: toJSON() -> toObject() * fix: typo in recursive calls to model.toObject() * fix: typo in recursive calls to model.toObject() * fix: missing --skip-build flag on serve command * fix: move test setup to ci yml files * fix: syntax error in circle.yml * fix: cache test-app instances * fix: increase default timeout * fix: run tests serially * fix: update method in controller * fix: properly set database driver in circleci * fix: integrate codecov with jest * feat: use mocks for fs tests * style: remove excess whitespace in watcher module * fix: enable eslint in test files * fix: use utc dates in serializer snapshots * deps: remove sinon in favor of jest mocks * test: run jest on appveyor * fix: syntax error in appveyor.yml * fix: remove ids from fixtures * test: do not use junit reporter * fix: ensure serializer snapshots have consistent sorting * fix: ensure serializer snapshots have consistent sorting * fix: ensure relationship snapshots have consistent sorting * fix: do not use snapshots in relationships module * deps: update flow-bin to version 0.39.0 * test: add unit test for adapters * test: add unit test for adapter utils * refactor: rename test directories to follow jest conventions * deps: update to jest 19 * test: improve coverage for controller * deps: update flow to version 0.40.0 * test: improve test coverage for fs package * test: improve coverage for parse path method * test: upload coverage results from appveyor * fix: cleanup connections after each test * chore: use yarn instead of npm * fix: wrap destroys in controller test in a transaction * fix: install yarn via powershell during appveyor builds * fix: do not use transactions without a connection pool * fix: use preinstalled yarn on appveyor builds * fix: run yarn commands in powershell in appveyor builds * fix: use npm link instead of yarn link on appveyor * fix: increase heap size for tests * fix: disable jest cache in appveyor builds * fix: run tests in parallel * feat: use in memory db with sqlite driver * fix: properly set worker count in ci * feat: cache test-app dependencies in ci * fix: do not specify worker count in circle.yml * deps: update outdated dependencies * fix: cleanup application instance methods * style: use block comment for flow files * style: add no-irregular-whitespace eslint rule * style: remove excess whitespace * deps: update dependencies * deps: update dependencies * deps: update test-app dependencies * fix: eslint errors in debugger * test: use circleci 2 * fix: syntax error in circle.yml * fix: change working directory in circle.yml * fix: move working directory entry in circle.yml * test: run tests synchronously in circleci * fix: migrate and seed database in circleci * fix: errors in circle.yml * fix: errors in circle.yml * fix: missing then in circle.yml seed database command * fix: use root database user in circleci * test: update appveyor.yml * test: use visual studio 2017 build image in appveyor.yml * fix: increase js heap size in appveyor builds * test: log heap usage in appveyor builds * test: run tests in parallel during appveyor builds * test: disable cache in appveyor builds * test: output color from jest in circleci builds * fix: remove force exit in circleci.yml * fix: force postgres builds to exit during circleci builds * test: use 2 runners during circleci builds * test: use 3 runners during circleci builds * test: use 4 runners during circleci builds * test: do not force postgres builds to exit during circleci builds * test: specify parallelism in circle.yml * test: cache dependencies during circleci builds * test: reuse yarn cache in circleci * test: use eslint cache in circleci * test: use better cache keys in circle.yml * test: reuse jest cache between circleci builds * fix: typo in circle.yml * fix: typo in circle.yml * test: rearrange build steps in circle.yml * test: rearrange build steps in circle.yml * test: do not specify number of workers during circleci builds * test: do not specify number of workers during circleci builds * test: do not specify number of workers during circleci builds * test: use 6 runners during circleci builds * test: use 8 runners during circleci builds * refactor: simplify pool logic in test-app database config * test: use cache in appveyor builds * test: use 4 runners during appveyor builds * test: remove unnecessary env var in circle.yml * test: change database pool config for appveyor builds * test: use 4 runners during appveyor builds * test: conditionally seed database during appveyor builds * test: use 2 runners during appveyor builds * test: do not use watchman in appveyor builds * test: use 3 runners during appveyor builds * test: use 2 runners during appveyor builds * test: try to set memory limit during appveyor builds * test: try to set memory limit during appveyor builds * test: try to set memory limit during appveyor builds * test: do not call jest directly in appveyor.yml * docs: add code of conduct and contributing documentation (#671) * docs: add code of conduct and contributing documentation fix: duplicate source materials entry in contributing.md docs: add preliminary content to code of conduct dx: add .nvmrc file (#672) docs: add build and test steps to contributing.md docs: add issue template docs: fix linter error for issue template docs: add docs for making documentation contributions docs: add link to rfcs repository in contributing.md docs: update readme and remove roadmap in favor of lux-rfcs repo style: whitespace change in contributing.md docs: left align column 2 of the commit style table in contributing.md docs: missing punctuation in code of conduct dx: add .nvmrc file (#672) docs: change irc to gitter in code of conduct * docs: use lux+moderators@postlight.com instead of lux@postlight.com * docs: copy changes in code of conduct docs: copy changes in code of conduct * docs: typo in contribting.md * docs: copy changes in contributing.md * docs: add instructions for reporting security vulnerabilities * docs: add a link to flow documentation in contributing.md * docs: typo in contributing.md * docs: add webstorm flow docs to contributing.md * docs: remove unecessary "that" in contributing.md * docs: widen the scope of the second bullet in the code of conduct * docs: add pull request template * docs: add "ways to contribute" section to contributing.md * test: do not report test coverage in appveyor * test: report coverage after appveyor builds * refactor: reduce usage of test app in unit tests * test: develop against node 7 * fix: failing snapshot tests for loader module * fix: failing postgres tests * refactor: develop against node 6.10.0 * fix: do not cache node_modules * fix: use epoch timestamp in circleci dependency cache key * test: lock appveyor node version to 6.10.0 * test: run test script in powershell in appveyor * style: use "test" instead of "it" in test files * chore: add back missing tests and upgrade flow * fix: eslint errors * deps: update outdated packages * docs: add jest to the useful links section of readme.md

zacharygolba force-pushed the docs-contributing branch from 642cbcd to 9a55646 Compare January 29, 2017 20:44

zacharygolba force-pushed the docs-contributing branch from 67d56c3 to 8ba3ce6 Compare January 30, 2017 14:46

Merge branch 'master' into docs-contributing

72a5b54

zacharygolba added the needs-review label Jan 30, 2017

ginatrapani reviewed Jan 31, 2017

View reviewed changes

zacharygolba added 9 commits January 31, 2017 15:51

Merge branch 'master' into docs-contributing

98f07d5

docs: use lux+moderators@postlight.com instead of lux@postlight.com

c642b2e

Merge branch 'docs-contributing' of https://github.com/postlight/lux …

e652a0d

…into docs-contributing

docs: copy changes in code of conduct

e3e8f47

docs: copy changes in code of conduct

docs: typo in contribting.md

0fccc61

docs: copy changes in contributing.md

241699c

Merge branch 'master' into docs-contributing

9d1229b

docs: add instructions for reporting security vulnerabilities

87a364d

docs: add a link to flow documentation in contributing.md

9ad8c6e

nickschot suggested changes Feb 8, 2017

View reviewed changes

Merge branch 'master' into docs-contributing

979cc9a

jamemackson approved these changes Feb 9, 2017

View reviewed changes

zacharygolba added 8 commits February 14, 2017 19:12

Merge branch 'master' into docs-contributing

20b53e3

docs: typo in contributing.md

f5b19cd

docs: add webstorm flow docs to contributing.md

ac8971f

docs: remove unecessary "that" in contributing.md

75ecea5

docs: widen the scope of the second bullet in the code of conduct

cf19bdc

docs: add pull request template

e3983a0

docs: add "ways to contribute" section to contributing.md

67302fb

Merge branch 'master' into docs-contributing

ddcc48a

nickschot approved these changes Mar 21, 2017

View reviewed changes

ginatrapani approved these changes Mar 21, 2017

View reviewed changes

zacharygolba merged commit 608409d into master Mar 21, 2017

zacharygolba deleted the docs-contributing branch March 21, 2017 14:18


		Contact: [lux@postlight.com](mailto:lux@postlight.com)

		* We are committed to providing a friendly, safe and welcoming environment for


		## Conduct

		Contact: [lux@postlight.com](mailto:lux@postlight.com)

docs: add code of conduct and contributing documentation #671

docs: add code of conduct and contributing documentation #671

Conversation

zacharygolba commented Jan 28, 2017 • edited Loading

To Do

Questions

Acknowledgement

codecov-io commented Jan 28, 2017 • edited by codecov bot Loading

Codecov Report

ginatrapani left a comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

zacharygolba Feb 3, 2017 • edited Loading

Choose a reason for hiding this comment

Choose a reason for hiding this comment

ginatrapani Jan 30, 2017 • edited Loading

Choose a reason for hiding this comment

zacharygolba Feb 7, 2017 • edited Loading

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

nickschot left a comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

jamemackson left a comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

zacharygolba commented Mar 20, 2017

zacharygolba commented Jan 28, 2017 •

edited

Loading

codecov-io commented Jan 28, 2017 •

edited by codecov bot

Loading

zacharygolba Feb 3, 2017 •

edited

Loading

ginatrapani Jan 30, 2017 •

edited

Loading

zacharygolba Feb 7, 2017 •

edited

Loading