Permalink
Browse files

Added CoC, contributor guidelines, and updated README.

  • Loading branch information...
1 parent 0c75e79 commit 6c2b07103f039d3289aeb5c7ce7496e5af91cd3c @jdantonio jdantonio committed Oct 5, 2015
Showing with 208 additions and 41 deletions.
  1. +64 −0 BUILDING.md
  2. +22 −0 CODE_OF_CONDUCT.md
  3. +114 −0 CONTRIBUTING.md
  4. +8 −41 README.md
View
@@ -0,0 +1,64 @@
+# Building
+
+All published versions of this gem (core, extension, and several platform-specific packages) are compiled,
+packaged, tested, and published using an open, automated process.
+This process can also be used to create pre-compiled binaries of the extension gem for virtually
+any platform. *Documentation is forthcoming...*
+
+```
+*MRI only*
+bundle exec rake build:native # Build concurrent-ruby-ext-<version>-<platform>.gem into the pkg dir
+bundle exec rake compile:extension # Compile extension
+
+*JRuby only*
+bundle exec rake build # Build JRuby-specific core gem (alias for `build:core`)
+bundle exec rake build:core # Build concurrent-ruby-<version>-java.gem into the pkg directory
+
+*All except JRuby*
+bundle exec rake build:core # Build concurrent-ruby-<version>.gem into the pkg directory
+bundle exec rake build:ext # Build concurrent-ruby-ext-<version>.gem into the pkg directory
+
+*When Docker IS installed*
+bundle exec rake build:windows # Build the windows binary <version> gems per rake-compiler-dock
+bundle exec rake build # Build core, extension, and edge gems, including Windows binaries
+
+*When Docker is NOT installed*
+bundle exec rake build # Build core, extension, and edge gems (excluding Windows binaries)
+
+*All*
+bundle exec rake clean # Remove any temporary products
+bundle exec rake clobber # Remove any generated file
+bundle exec rake compile # Compile all the extensions
+```
+
+## Publishing the Gem
+
+To create the build you'll need to have both MRI and JRuby installed and configured with the appropriate build tools and libraries. To create the Windows build you'll need to install docker. If you are on OS X you'll also need boot2docker. Once you have all that setup, everything if fairly automated:
+
+* Update`version.rb`
+* Update the CHANGELOG
+* Switch to MRI
+ - Make sure docker is running (otherwise the windows build task will not be available)
+ - Run `bundle exec rake clean` to get rid of old artifacts
+ - Run `bundle exec rake build` to build core, ext, ext-windows, and edge into the *pkg* directory
+* Switch to JRuby
+ - Delete *Gemfile.lock* and run `bundle install` (this isn't always necessary, but our multi-gem setup sometimes confuses bundler)
+ - Run `bundle exec rake clean` to get rid of old artifacts
+ - Run `bundle exec rake build` to build core-java into the *pkg* directory
+* If everything looks good, update git
+ - Commit the changes
+ - Tag the master branch with the version number
+ - Push to GitHub
+* Update the Yard documentation
+ - Run `bundle exec rake yard` to update the documentation
+ - Run `bundle exec rake yard:push` to push the docs to GitHub Pages
+* For each gem file in *pkg* run `gem push pkg/concurrent-ruby-<...>.gem` to push to Rubygems
+* Update the release in GitHub
+ - Select the `releases` link on the main repo page
+ - Press the `Edit` button to edit the release
+ - Name the release based on the version number
+ - Add a description
+ - Attach all the `*.gem` file
+ - Save the updated release
+
+The compiled and build gem packages can be tested using the scripts in the `build-tests` folder. The `runner.rb` script is the main test runner. It will run all tests which are available on the given platform. It will install the various gem packages (core, ext, and edge) as necessary, run the tests, then clean up after itself.
View
@@ -0,0 +1,22 @@
+# Contributor Code of Conduct
+
+As contributors and maintainers of this project, and in the interest of fostering an open and welcoming community, we pledge to respect all people who contribute through reporting issues, posting feature requests, updating documentation, submitting pull requests or patches, and other activities.
+
+We are committed to making participation in this project a harassment-free experience for everyone, regardless of level of experience, gender, gender identity and expression, sexual orientation, disability, personal appearance, body size, race, ethnicity, age, religion, or nationality.
+
+Examples of unacceptable behavior by participants include:
+
+* The use of sexualized language or imagery
+* Personal attacks
+* Trolling or insulting/derogatory comments
+* Public or private harassment
+* Publishing other's private information, such as physical or electronic addresses, without explicit permission
+* Other unethical or unprofessional conduct.
+
+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. By adopting this Code of Conduct, project maintainers commit themselves to fairly and consistently applying these principles to every aspect of managing this project. Project maintainers who do not follow or enforce the Code of Conduct may be permanently removed from the project team.
+
+This code of conduct applies both within project spaces and in public spaces when an individual is representing the project or its community.
+
+Instances of abusive, harassing, or otherwise unacceptable behavior may be reported by opening an issue or contacting one or more of the project maintainers.
+
+This Code of Conduct is adapted from the [Contributor Covenant](http://contributor-covenant.org), version 1.2.0, available at [http://contributor-covenant.org/version/1/2/0/](http://contributor-covenant.org/version/1/2/0/)
View
@@ -0,0 +1,114 @@
+# Contributing to Concurrent Ruby
+
+You want to contribute? Thank you! Concurrent Ruby is work of [many contributors](https://github.com/ruby-concurrency/concurrent-ruby/graphs/contributors). You're encouraged to submit [pull requests](https://github.com/ruby-concurrency/concurrent-ruby/pulls), [propose features and discuss issues](https://github.com/ruby-concurrency/concurrent-ruby/issues). When in doubt, ask a question in the [Concurrent Ruby gitter.im chatroom](https://gitter.im/ruby-concurrency/concurrent-ruby) or on the [mailing list](https://groups.google.com/forum/#!forum/concurrent-ruby).
+
+#### Find Something to Work on
+
+If you want to contribute but aren't sure what to work on, we keep our list of current todos on our [issues page](https://github.com/ruby-concurrency/concurrent-ruby/issues). Before starting, feel free to chat with us on [gitter](https://gitter.im/ruby-concurrency/concurrent-ruby).
+
+#### Fork the Project
+
+Fork the [project on Github](https://github.com/ruby-concurrency/concurrent-ruby) and check out your copy.
+
+```
+git clone https://github.com/contributor/concurrent-ruby.git
+cd concurrent-ruby
+git remote add upstream https://github.com/ruby-concurrency/concurrent-ruby.git
+```
+
+#### Create a Topic Branch
+
+Make sure your fork is up-to-date and create a topic branch for your feature or bug fix.
+
+```
+git checkout master
+git pull upstream master
+git checkout -b my-feature-branch
+```
+
+#### Bundle Install, Buildn and Test
+
+
+Ensure that you can build the project and run tests.
+
+Please note that Concurrent Ruby includes native Java and (optional) C extensions. When building you will need the appropriate build tools for your platform. If you don't have the build tools installed that's OK. The tests can still be run. A few tests nay fail, but these are just the tests that verify that the extensions exist. You can usually ignore these locally if you are working on the pure Ruby parts of the library (which is most of the lib).
+
+```
+bundle install
+bundle exec rake
+```
+
+#### Write Tests
+
+Try to write a test that reproduces the problem you're trying to fix or describes a feature that you want to build. Add to [specs](https://github.com/ruby-concurrency/concurrent-ruby/tree/master/spec).
+
+We definitely appreciate pull requests that highlight or reproduce a problem, even without a fix.
+
+#### Write Code
+
+Implement your feature or bug fix.
+
+Make sure that `bundle exec rake` completes without errors.
+
+#### Write Documentation
+
+Document any external behavior in the [README](README.md).
+
+#### Commit Changes
+
+Make sure git knows your name and email address:
+
+```
+git config --global user.name "Your Name"
+git config --global user.email "contributor@example.com"
+```
+
+Writing good commit logs is important. A commit log should describe what changed and why.
+
+```
+git add ...
+git commit
+```
+
+#### Push
+
+```
+git push origin my-feature-branch
+```
+
+#### Make a Pull Request
+
+Go to https://github.com/contributor/concurrent-ruby and select your feature branch. Click the 'Pull Request' button and fill out the form. Pull requests are usually reviewed within a few days.
+
+#### Rebase
+
+If you've been working on a change for a while, rebase with upstream/master.
+
+```
+git fetch upstream
+git rebase upstream/master
+git push origin my-feature-branch -f
+```
+
+#### Update CHANGELOG Again
+
+Update the [CHANGELOG](CHANGELOG.md) with a description of what you have changed.
+
+Amend your previous commit and force push the changes.
+
+```
+git commit --amend
+git push origin my-feature-branch -f
+```
+
+#### Check on Your Pull Request
+
+Go back to your pull request after a few minutes and see whether it passed muster with Travis-CI and AppVeyor. Everything should look green, otherwise fix issues and amend your commit as described above.
+
+Please note that testing concurrency is hard. Very hard. We have a few tests that occasionally fail due (mostly) to incorrect synchronization within the test itself. If everything passes locally but you see an error on CI, it's possibly you've become victim to ont of the tests. Don't worry, the Concurrent Ruby team reviews the tests output of all failed CI runs and will let you know if the failing test is unrelated to your commit.
+
+#### Thank You
+
+Please do know that we really appreciate and value your time and work. We love you, really.
+
+And also, a special thank you to the [Volt](https://github.com/voltrb/volt) team for writing an awesome guied for contributers. We have borroed liberally from theirs.
View
@@ -49,6 +49,14 @@ MRI 1.9.3, 2.0, 2.1, 2.2, JRuby (1.9 mode), and Rubinius 2.x are supported.
This gem should be fully compatible with any interpreter that is compliant with Ruby 1.9.3 or newer.
Java 8 is preferred for JRuby but every Java version on which JRuby 9000 runs will be supported.
+## Thread Safety
+
+*Concurrent Ruby makes the strongest thread safety guarantees of any Ruby concurrency library. We are the only library with a published [memory model](https://github.com/ruby-concurrency/concurrent-ruby/blob/master/doc/synchronization.md) which provides consistent behavior and guarantees on all three of the main Ruby interpreters (MRI/CRuby, JRuby, and Rubinius).*
+
+Every abstraction in this library is thread safe. Similarly, all are deadlock free and many are fully lock free. Specific thread safety guarantees are documented with each abstraction.
+
+It is critical to remember, however, that Ruby is a language of mutable references. *No* concurrency library for Ruby can ever prevent the user from making thread safety mistakes (such as sharing a mutable object between threads and modifying it on both threads) or from creating deadlocks through incorrect use of locks. All the library can do is provide safe abstractions which encourage safe practices. Concurrent Ruby provides more safe concurrency abstractions than any other Ruby library, many of which support the mantra of ["Do not communicate by sharing memory; instead, share memory by communicating"](https://blog.golang.org/share-memory-by-communicating). Concurrent Ruby is also the only Ruby library which provides a full suite of thread safe and immutable variable types and data structures.
+
## Features & Documentation
We have a roadmap guiding our work toward the [v1.0.0 release](https://github.com/ruby-concurrency/concurrent-ruby/issues/257).
@@ -229,39 +237,6 @@ and load the appropriate C extensions.
No gems should depend on `concurrent-ruby-ext`. Doing so will force C extensions on your users.
The best practice is to depend on `concurrent-ruby` and let users to decide if they want C extensions.
-### Building
-
-All published versions of this gem (core, extension, and several platform-specific packages) are compiled,
-packaged, tested, and published using an open, [automated process](https://github.com/ruby-concurrency/rake-compiler-dev-box).
-This process can also be used to create pre-compiled binaries of the extension gem for virtually
-any platform. *Documentation is forthcoming...*
-
-```
-*MRI only*
-bundle exec rake build:native # Build concurrent-ruby-ext-<version>-<platform>.gem into the pkg dir
-bundle exec rake compile:extension # Compile extension
-
-*JRuby only*
-bundle exec rake build # Build JRuby-specific core gem (alias for `build:core`)
-bundle exec rake build:core # Build concurrent-ruby-<version>-java.gem into the pkg directory
-
-*All except JRuby*
-bundle exec rake build:core # Build concurrent-ruby-<version>.gem into the pkg directory
-bundle exec rake build:ext # Build concurrent-ruby-ext-<version>.gem into the pkg directory
-
-*When Docker IS installed*
-bundle exec rake build:windows # Build the windows binary <version> gems per rake-compiler-dock
-bundle exec rake build # Build core, extension, and edge gems, including Windows binaries
-
-*When Docker is NOT installed*
-bundle exec rake build # Build core, extension, and edge gems (excluding Windows binaries)
-
-*All*
-bundle exec rake clean # Remove any temporary products
-bundle exec rake clobber # Remove any generated file
-bundle exec rake compile # Compile all the extensions
-```
-
## Maintainers
* [Jerry D'Antonio](https://github.com/jdantonio) (creator)
@@ -277,14 +252,6 @@ bundle exec rake compile # Compile all the extensions
* [Charles Oliver Nutter](https://github.com/headius) for the `atomic` and `thread_safe` gems
* [thedarkone](https://github.com/thedarkone) for the `thread_safe` gem
-## Contributing
-
-1. Fork it
-2. Create your feature branch (`git checkout -b my-new-feature`)
-3. Commit your changes (`git commit -am 'Add some feature'`)
-4. Push to the branch (`git push origin my-new-feature`)
-5. Create new Pull Request
-
## License and Copyright
*Concurrent Ruby* is free software released under the [MIT License](http://www.opensource.org/licenses/MIT).

0 comments on commit 6c2b071

Please sign in to comment.