diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index 0a9b5cdc..c0339be7 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -1,41 +1,82 @@ # Contributing to OSEM -Our open source project is open to contributions. Open your [issue](https://github.com/openSUSE/osem/issues/new) and send a PR! +We here at OSEM are open for all types of contributions from anyone. Tell us about our [issues/ideas](https://github.com/openSUSE/osem/issues/new), propose code changes via [pull requests](https://help.github.com/articles/using-pull-requests) or contribute artwork and documentation. -We welcome new developers, and we actively participate in mentoring programs, such as [GSoC](https://summerofcode.withgoogle.com/) and [RGSoC](https://railsgirlssummerofcode.org/). +We welcome all new developers and are also prepared to mentor you through your first contributions! All OSEM maintainers are seasoned developers and have participated in mentoring programs, such as [GSoC](https://summerofcode.withgoogle.com/) and [RGSoC](https://railsgirlssummerofcode.org/). -## Request for contributions -We are always looking for contributions to OSEM. Read this guide on how to do that. +We need your input and contributions to OSEM. In particular we seek the following types: -In particular, this community seeks the following types of contributions: +* **code**: contribute your expertise in an area by helping us expand OSEM with features/bugfixes/UX +* **code editing**: fix typos, clarify language, and generally improve the quality of the content of OSEM +* **ideas**: participate in an issues thread or start your own to have your voice heard -* code: contribute your expertise in an area by helping us expand OSEM -* ideas: participate in an issues thread or start your own to have your voice heard. -* code editing: fix typos, clarify language, and generally improve the quality of the content of OSEM +Read this guide on how to do that. -## Running OSEM in development -We are using [Vagrant](https://www.vagrantup.com/) to create our development environments. +## How to contribute code +1. Fork the repository and make a pull-request with your changes + 1. Make sure that the test suite passes and that you comply to our code style + 1. Please increase code coverage with your pull request +1. One of the OSEM maintainers will review your pull-request + 1. If you are already a contributor and you get a positive review, you can merge your pull-request yourself + 1. If you are not already a contributor, one of the existing contributors will merge your pull-request -1. Install [Vagrant](https://www.vagrantup.com/downloads.html) and [VirtualBox 5.0.10](https://www.virtualbox.org/wiki/Download_Old_Builds_5_0). Both tools support Linux, MacOS and Windows. +## Development Environment -2. Install [vagrant-exec](https://github.com/p0deje/vagrant-exec): +### with docker-compose +To isolate you host system from OSEM development we have prepared a container +based development environment, based on [docker](https://www.docker.com/) and +[docker-compose](https://docs.docker.com/compose/). Here's a step by step guide +how to set it up. +1. Set up the development environment: + ```bash + docker-compose run --rm osem bundle exec rake setup:bootstrap ``` + +1. Start the development environment: + ```bash + docker-compose up --build + ``` + +1. Check out your OSEM rails app. You can access the app at http://localhost:3000. Whatever you change in your cloned repository will have effect in the development environment. Sign up, the first user will be automatically assigned the admin role. + +1. Changed something? Test your changes! + ```bash + docker-compose run --rm osem bundle exec rspec spec + ``` + +1. Issue any standard `rails`/`rake`/`bundler` command + ```bash + docker-compose run --rm osem bundle exec rake db:version + ``` + +1. Or explore the development environment: + ```bash + docker-compose exec osem_1 /bin/bash -l + ``` + +**WARNING**: Since we mount the repository into our container, your user id and the id of the osem user inside the container need to be the same. If your user id (`id -u`) is something else than `1000` you can copy the docker-compose override example file and in it, set your user id in the variable +*CONTAINER_USERID*. + +```bash +cp docker-compose.override.yml.example docker-compose.override.yml +``` + +### with Vagrant +Another option is using [Vagrant](https://www.vagrantup.com/) and [VirtualBox 5.0.10](https://www.virtualbox.org/wiki/Download_Old_Builds_5_0) to create your development environment. + +1. Install [vagrant-exec](https://github.com/p0deje/vagrant-exec): + + ```bash vagrant plugin install vagrant-exec ``` -3. Clone this code repository: - - ``` - git clone https://github.com/openSUSE/osem.git - ``` - -4. Execute Vagrant in the cloned directory: +1. Start the development environment ``` vagrant up ``` -5. Start your OSEM rails app: +1. Start OSEM inside the development environment ``` vagrant exec /vagrant/bin/rails server -b 0.0.0.0 @@ -50,91 +91,34 @@ You can access the app [localhost:3000](http://localhost:3000). Whatever you cha vagrant exec bundle exec rspec spec ``` -8. Explore the development environment: - - ``` - vagrant ssh - ``` - -9. Or issue any standard `rails`/`rake`/`bundler` command by prepending `vagrant exec` +9. Issue any standard `rails`/`rake`/`bundler` command ``` vagrant exec bundle exec rake db:migrate ``` -## How to contribute code -* Prerequisite: familiarity with [GitHub Pull Requests](https://help.github.com/articles/using-pull-requests) and issues. -* Fork the repository and make a pull-request with your changes - * Make sure that the test suite passes before you request a pull and that you comply to our ruby styleguide. - * Please increase code coverage by your pull request (coveralls or simplecov locally will give you insight) -* One of the OSEM maintainers will review your pull-request - * If you are already a contributor and you get a positive review, you can merge your pull-request yourself - * If you are not already a contributor please request a merge via the pull-request comments +8. Or explore the development environment: -### Coding Style -We are using [rubocop](https://github.com/bbatsov/rubocop) as a style checker. It is checking code style each time the test suite runs. You can run it locally with + ``` + vagrant ssh + ``` -```shell -vagrant exec bundle exec rubocop -``` +## Want to know more? +In our wiki you can find more information about what is possible in our development environment, +how we work with each other on github or other topics of interest for developers. Visit us at +>>>>>>> Introduces docker-compose to the contribution guide -You can read through current enabled rules in `.rubocop.yml` file. Explanations of the defined [rules](http://rubydoc.info/github/bbatsov/rubocop/master/frames) can be found in modules [Cop::Lint](http://rubydoc.info/github/bbatsov/rubocop/master/Rubocop/Cop/Lint) and [Cop::Style](http://rubydoc.info/github/bbatsov/rubocop/master/Rubocop/Cop/Style) and [Cop:Rails](https://rubocop.readthedocs.io/en/latest/cops_rails/). -Additionally you can read through the [ruby style-guide](https://github.com/bbatsov/ruby-style-guide) to better understand core principles. - -### Git Hooks -We use [overcommit](https://github.com/brigade/overcommit) to automate Rubocop in pre-commit git hooks. You can activate it locally with: - -```shell -# Install overcommit gem -vagrant exec gem install overcommit - -# Activate overcommit -vagrant exec overcommit install -``` - -You can read through the current enabled hooks in the `.overcommit.yml` file. - -### Test Suite -We are using [rspec](http://rspec.info/)+[capybara](http://teamcapybara.github.io/capybara/)+[factory bot](https://github.com/thoughtbot/factory_bot) as a test suite. You can run it locally - -```shell -vagrant exec bundle exec rspec -# or, in parallel -vagrant exec bundle exec rake knapsack:rspec -``` - -### Email Notifications -**Note**: We use [letter_opener](https://github.com/ryanb/letter_opener) in development environment. You can check out your mails by visiting [localhost:3000/letter_opener](http://localhost:3000/letter_opener). - -### Using iChain in test mode -[devise_ichain_authenticatable](https://github.com/openSUSE/devise_ichain_authenticatable) comes with -test mode, which can be useful in development phase in which an iChain proxy is -not usually configured or even available. You can enable ichain authentication by setting `OSEM_ICHAIN_ENABLED` equal to `true` in `.env` file. You would also need to set following options in `devise.rb`: - -```Ruby -# Activate the test mode -config.ichain_test_mode = true - -# 'testuser' user will be permanently signed in. -config.ichain_force_test_username = "testuser" - -# set email of 'testuser' -config.ichain_force_test_attributes = {:email => "testuser@example.com"} -``` - -### Using OpenID in developement -OSEM supports [OpenID](https://openid.net/) logins via [OmniAuth](https://github.com/omniauth/omniauth) and related provider specific gems. OmniAuth provides the ablity to define per-provider mock accounts for testing. The supported providers are Facebook, Google, openSUSE and GitHub. If you want to use the OSEM provided mock accounts you need to set the appropriate `OSEM_PROVIDER_KEY` and `OSEM_PROVIDER_SECRET` environment variables to a non empty string in the `.env` file. - -e.g. -``` -OSEM_GITHUB_KEY='sample' -OSEM_GITHUB_SECRET='sample' -``` - -If you don't already have a `.env` file you can use the `dotenv.example` as a template. +https://github.com/openSUSE/osem/wiki ## Code of Conduct -OSEM is part of the openSUSE project. We follow all the [openSUSE Guiding Principles!](http://en.opensuse.org/openSUSE:Guiding_principles) If you think someone doesn't do that, please let us know at maintainers@osem.io +OSEM is part of the openSUSE project. We follow all the +[openSUSE Guiding Principles!](http://en.opensuse.org/openSUSE:Guiding_principles) +If you think someone doesn't do that, please let us know at maintainers@osem.io or +address your concerns to the [openSUSE Board](https://en.opensuse.org/openSUSE:Board). ## Contact -GitHub issues are the primary way for communicating about specific proposed changes to this project. If you have other questions feel free to subscribe to the [opensuse-web@opensuse.org](http://lists.opensuse.org/opensuse-web/) mailinglist, all OSEM contributors are on that list! Additionally you can use #osem channel on freenode IRC. +GitHub issues and pull requests are the primary way for communicating about specific proposed +changes to this project. If you have other questions feel free to subscribe to +the [opensuse-web@opensuse.org](http://lists.opensuse.org/opensuse-web/) +mailinglist, all OSEM contributors are on that list! Additionally you can use the #osem channel +on freenode IRC.