From b4b93e293d50e5bef5fcdadb76dbc6ac16821404 Mon Sep 17 00:00:00 2001 From: Matthew Podwysocki Date: Fri, 11 Aug 2017 00:28:40 -0400 Subject: [PATCH] feat(docs): Adding basic contribution docs --- CODE_OF_CONDUCT.md | 74 +++++++++++++++++ CONTRIBUTING.md | 197 +++++++++++++++++++++++++++++++++++++++++++++ LICENSE | 2 +- readme.md | 12 +++ 4 files changed, 284 insertions(+), 1 deletion(-) create mode 100644 CODE_OF_CONDUCT.md create mode 100644 CONTRIBUTING.md diff --git a/CODE_OF_CONDUCT.md b/CODE_OF_CONDUCT.md new file mode 100644 index 00000000..32a47d56 --- /dev/null +++ b/CODE_OF_CONDUCT.md @@ -0,0 +1,74 @@ +# Contributor Covenant Code of Conduct + +## Our Pledge + +In the interest of fostering an open and welcoming environment, we as +contributors and maintainers pledge to making participation in our project and +our community a harassment-free experience for everyone, regardless of age, body +size, disability, ethnicity, gender identity and expression, level of experience, +nationality, personal appearance, race, religion, or sexual identity and +orientation. + +## Our Standards + +Examples of behavior that contributes to creating a positive environment +include: + +* Using welcoming and inclusive language +* Being respectful of differing viewpoints and experiences +* Gracefully accepting constructive criticism +* Focusing on what is best for the community +* Showing empathy towards other community members + +Examples of unacceptable behavior by participants include: + +* The use of sexualized language or imagery and unwelcome sexual attention or +advances +* Trolling, insulting/derogatory comments, and personal or political attacks +* Public or private harassment +* Publishing others' private information, such as a physical or electronic + address, without explicit permission +* Other conduct which could reasonably be considered inappropriate in a + professional setting + +## Our Responsibilities + +Project maintainers are responsible for clarifying the standards of acceptable +behavior and are expected to take appropriate and fair corrective action in +response to any instances of unacceptable behavior. + +Project maintainers have the right and responsibility to remove, edit, or +reject comments, commits, code, wiki edits, issues, and other contributions +that are not aligned to this Code of Conduct, or to ban temporarily or +permanently any contributor for other behaviors that they deem inappropriate, +threatening, offensive, or harmful. + +## Scope + +This Code of Conduct applies both within project spaces and in public spaces +when an individual is representing the project or its community. Examples of +representing a project or community include using an official project e-mail +address, posting via an official social media account, or acting as an appointed +representative at an online or offline event. Representation of a project may be +further defined and clarified by project maintainers. + +## Enforcement + +Instances of abusive, harassing, or otherwise unacceptable behavior may be +reported by contacting the project team at [INSERT EMAIL ADDRESS]. All +complaints will be reviewed and investigated and will result in a response that +is deemed necessary and appropriate to the circumstances. The project team is +obligated to maintain confidentiality with regard to the reporter of an incident. +Further details of specific enforcement policies may be posted separately. + +Project maintainers who do not follow or enforce the Code of Conduct in good +faith may face temporary or permanent repercussions as determined by other +members of the project's leadership. + +## Attribution + +This Code of Conduct is adapted from the [Contributor Covenant][homepage], version 1.4, +available at [http://contributor-covenant.org/version/1/4][version] + +[homepage]: http://contributor-covenant.org +[version]: http://contributor-covenant.org/version/1/4/ \ No newline at end of file diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md new file mode 100644 index 00000000..70819fc7 --- /dev/null +++ b/CONTRIBUTING.md @@ -0,0 +1,197 @@ +# Contributing to IxJS + +[Read and abide by the Code of Conduct](CODE_OF_CONDUCT.md)! Even if you don't read it, +it still applies to you. Ignorance is not an exemption. + +Contents + + + + + +- [Submitting a Pull Request (PR)](#submitting-a-pull-request-pr) + - [After your pull request is merged](#after-your-pull-request-is-merged) +- [Coding Style Guidelines](#coding-style-guidelines) +- [Unit Tests](#unit-tests) + - [CI Tests](#ci-tests) +- [Commit Message Guidelines](#commit-message-guidelines) + - [Commit Message Format](#commit-message-format) + - [Revert](#revert) + - [Type](#type) + - [Scope](#scope) + - [Subject](#subject) + - [Body](#body) + - [Footer](#footer) + + + +(This document is a work and progress and is subject to change) + +## Submitting a Pull Request (PR) +Before you submit your Pull Request (PR) consider the following guidelines: + +* Search [GitHub](https://github.com/ReactiveX/IxJS/pulls) for an open or closed PR + that relates to your submission. You don't want to duplicate effort. +* Make your changes in a new git branch: + + ```shell + git checkout -b my-fix-branch master + ``` + +* Create your patch, following [code style guidelines](#coding-style-guidelines), and **including appropriate test cases**. +* Run the full test suite and ensure that all tests pass. +* Run the micro and macro performance tests against your feature branch and compare against master + to ensure performance wasn't changed for the worse. +* Commit your changes using a descriptive commit message that follows our + [commit message guidelines](#commit-message-guidelines). Adherence to these conventions + is necessary because release notes are automatically generated from these messages. + + ```shell + git commit -a + ``` + Note: the optional commit `-a` command line option will automatically "add" and "rm" edited files. + +* Push your branch to GitHub: + + ```shell + git push origin my-fix-branch + ``` + +* In GitHub, send a pull request to `IxJS:master`. +* If we suggest changes then: + * Make the required updates. + * Re-run the test suites to ensure tests are still passing. + * Re-run performance tests to make sure your changes didn't hurt performance. + * Rebase your branch and force push to your GitHub repository (this will update your Pull Request): + + ```shell + git rebase master -i + git push -f + ``` + +That's it! Thank you for your contribution! + + +### After your pull request is merged + +After your pull request is merged, you can safely delete your branch and pull the changes +from the main (upstream) repository: + +* Delete the remote branch on GitHub either through the GitHub web UI or your local shell as follows: + + ```shell + git push origin --delete my-fix-branch + ``` + +* Check out the master branch: + + ```shell + git checkout master -f + ``` + +* Delete the local branch: + + ```shell + git branch -D my-fix-branch + ``` + +* Update your master with the latest upstream version: + + ```shell + git pull --ff upstream master + ``` + +## Coding Style Guidelines + +- Please use proper types and generics throughout your code. +- 2 space indentation only +- favor readability over terseness + +(TBD): For now try to follow the style that exists elsewhere in the source, and use your best judgment. + + +## Unit Tests + +Unit tests are located under the [spec directory](/spec). Unit tests are written using [tape](https://github.com/substack/tape) + +Each operator under test must be in its own file to cover the following cases: + +- Never +- Empty +- Single/Multiple Values +- Error in the sequence + +If the operator accepts a function as an argument from the user/developer (for example `filter(fn)` or `zip(a, fn)`), +then it must cover the following cases: + +- Success with all values in the callback +- Success with the context, if any allowed in the operator signature +- If an error is thrown + +### CI Tests + +- Using [Travis](https://travis-ci.org/) on your forked version of IxJS will allow running CI tests on that fork before submitting a PR to master + - Simply create a `Travis` account and add your fork as a new project +- As master runs both of these tests per each check in, it'd be welcome to setup those test before creating your PR + +## Commit Message Guidelines + +We have very precise rules over how our git commit messages can be formatted. This leads to **more +readable messages** that are easy to follow when looking through the **project history**. But also, +we use the git commit messages to **generate the IxJS change log**. Helper script `npm run commit` +provides command line based wizard to format commit message easily. + +### Commit Message Format +Each commit message consists of a **header**, a **body** and a **footer**. The header has a special +format that includes a **type**, a **scope** and a **subject**: + +``` +(): + + + +