Skip to content

Latest commit

 

History

History
183 lines (128 loc) · 9.94 KB

contribute.md

File metadata and controls

183 lines (128 loc) · 9.94 KB
Raw
layout title
contribute
Contributing to Foreman

Contributing

Read the Foreman handbook

The Foreman is an open-source project that's licensed under the GNU General Public License version 3.
Contributions of all types are gladly accepted!

Attend some Events

The Foreman has a growing list of community events - check the events page for more details. If there's nothing suitable in your area, why not consider creating an event!

Code-related contributions

These types of tasks generally require a familiarity with Ruby (on Rails) development or RPM/Debian packaging. If you are still new to Rails, community members can help you if you get stuck with something or have any other questions.

You will need to download a copy of the current development code. The official code repository is located on GitHub. All changes are made in the develop branch.

Supported Ruby versions

In general the latest Ruby should work. However if you are just starting out, you may want to develop against one of the versions that we test against to reduce the chances of you hitting an unexpected issue, although this is not required.

You can see what versions we are currently testing against on our Jenkins CI server here: http://ci.theforeman.org/view/Foreman%20pipeline/job/test_develop/

Any version of Ruby that is older than those listed is not supported.

Supported Node.js versions

In general, the latest stable Node.js should work. However if you are just starting out, you may want to develop against one of the versions that we test against to reduce the chances of you hitting an unexpected issue, although this is not required.

You can see what versions we are currently testing against on our Travis CI runs in the .travis.yml file in the foreman repository.

Any version of Node.js that is older than those listed is not supported.

For populating the node_modules folder, npm version 4 or later is required. Alternatively, yarn can also be used.

Setup development environment

  • Fork theforeman/foreman to your GitHub account. This will create a "foreman" repo under your GitHub username.
  • Clone the fork you just created to your development system: {% highlight bash %} git clone https://github.com//foreman.git {% endhighlight %}
  • Reference theforeman/foreman as upstream: {% highlight bash %} cd foreman git remote add upstream https://github.com/theforeman/foreman.git git fetch upstream {% endhighlight %}
  • Copy config/settings.yaml.example to config/settings.yaml
  • Install all required gems and node modules: {% highlight bash %} bundle install npm install {% endhighlight %}

You may get some failures when installing the required gems due to some native libraries being required (notably libvirt-devel & postgresql-devel) so you will need to install these via your distributions normal package manager (e.g. yum install libvirt-devel postgresql-devel for RHEL/Fedora based distributions).

You can also exclude these features by using bundle install --without libvirt postgresql etc (groups are under bundler.d/).

Setup test environment

  1. Copy config/database.yml.example to config/database.yml
  2. Create your database: bundle exec bin/rake db:migrate
  3. Run all the tests: bundle exec bin/rake test
  4. Or a single test: bundle exec bin/rake test test/functional/your_test.rb
  5. Once done, stop any background processes with bundle exec spring stop (more info)

Startup foreman

  1. Follow steps 1, 2 and 3 from the section "setup test environment" if you haven't done so already
  2. Populate database: bundle exec bin/rake db:seed and take note of the password it generates
  3. Startup the server: bundle exec foreman start
  4. Navigate to http://localhost:3000
  5. Login as admin with the password from the db:seed step earlier (or reset it with bundle exec bin/rake permissions:reset)

Submit Patches

First, make sure you are a member of the Foreman Developers mailing list.

Patches to fix bugs or add new features are always appreciated. If you are going to work on a specific issue, make a note in the issue details so the developers will know what you're working on.

We try to keep a one commit per bug/feature policy, please try to create an issue which is specific for your patch details.

Please make sure there is a Redmine issue open for the change you are going to submit, as you will want to reference it in your commit message; this is very helpful when generating release notes.

  • Create a feature/topic branch

{% highlight bash %} git checkout -b # Example: git checkout -b 1656-add_TB_support {% endhighlight %}

  • Make changes and commit. Please reference the Redmine issue this commit addresses via "Refs" or "Fixes" in the commit message. See Coding Standards guide for more details.

{% highlight bash %} git add <modifiedFile(s)> git commit -m 'Fixes # - ' {% endhighlight %}

  • Push topic branch to your fork:

{% highlight bash %} git push origin # Example: git push origin 1656-add_TB_support {% endhighlight %}

Once you have followed this process once, it becomes much simpler to add future patches!

Merge upstream develop to local develop

{% highlight bash %} git fetch upstream git checkout develop git merge upstream/develop develop git push origin develop {% endhighlight %}

Now follow step 4 to the end from above.

Projects / mentoring

Please see this page for details on our current projects.

Non-code related contributions

These don't require any software development experience, just some time and the desire to help.

User support

Helping out other users in the "Forums" is always useful. Frequent problems or questions should be brought up so the wiki can be updated to help future users.

Testing is also very welcome, for any issue encountered, please open a bug / feature request.

Bug reporting

Even the simplest of bugs reported helps us make the project better. The issue tracker is located at http://projects.theforeman.org/projects/foreman/issues, and you should follow these guidelines:

  • Ensure the correct project is selected - the link above is for the Foreman UI itself, you can use this list for the other projects.
  • Use an understandable, descriptive title, e.g. "Clicking the Template review button gives a 500 server error" rather than "Template review is broken"
  • Provide whatever context you can - your host operating system, Foreman version(s), ruby version, etc
  • State what you were trying to achieve - provide steps to reproduce your problem where possible
  • State what happened in more detail than the title - provide logs where possible
  • State what you expected to happen - this helps us correct misinterpretations of features

Feature requests

If you're submitting a feature request or user story, please provide the context for the feature, especially the problem you're trying to solve, and your preferred implementation (if you have one). This will lead to a clear record of the discussion and eventual decision.

It's acceptable to head over to the dev mailing list to start a discussion if you have an idea you'd like more input on, before submitting tickets. Be sure to mention the appropriate thread in the ticket, so the context can be found in the future.

Issue triage

Sometimes issues are reported without all the above information needed. Getting the details of the bug or feature from the reporter and the community will help everyone understand what is needed. Our issue tracker can be found here: http://projects.theforeman.org/projects/foreman/issues, and see the above section for issue guidelines.

Translations

The Foreman application has been translated into a number of languages, which require regular updates as strings are added and changed in each release. We're also on the lookout for new translations if you speak a language that Foreman isn't yet available for. Join in the effort on our Transifex project.

Documentation and web site

We're trying to maintain high quality, authoritative documentation in the Foreman manual as part of this web site. Any contributions, such as adding content, removing outdated information or improving the style and layout are greatly appreciated.

Both the manual and the web site are contained in our theforeman.org repository. See the README.md to get started. Contributions to this project are licensed under Creative Commons Attribution-ShareAlike 3.0.

Design and User interface

Foreman 1.11 and above uses Patternfly as its base design. Any improvements or suggestions on how to implement this better, or on re-implementing particular pages are very welcome, and could help every user. Design discussion should happen on the dev mailing list.

Hosted hardware

We have an ever-growing number of contributions and other plugins and projects that require computing power, mostly in our Jenkins CI environment. We also have package builders, web hosting and other services to run.

Foreman has a number of generous sponsors who provide hosted, publicly accessible servers (usually virtual machines) or cloud accounts that we can use. Please see the sponsors page for more details.