gunghogeoduck/osem-fcy
1
0
Fork 0
mirror of https://github.com/openSUSE/osem.git synced 2026-08-13 19:54:02 +00:00
Code Issues Projects Releases Packages Wiki Activity Actions

Introduces docker-compose to the contribution guide

Browse source 
Introduces a section about the docker-compose development environment.
I have also tried to shorten the guide, by moving some things to the wiki,
so it's not too overwhelming for new contributors.
This commit is contained in:
Henne Vogelsang 2018-09-05 23:13:53 +02:00 • committed by Ana María Martínez Gómez
parent 8fd3004d7f
commit 0eb1ef337a
1 changed files with 80 additions and 96 deletions
Download patch file Download diff file Expand all files Collapse all files

176
CONTRIBUTING.md
View file

@ -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.