CONTRIBUTING.md

   1 # Contribute to GitLab
   2
   3 This guide details how to use issues and pull requests to improve GitLab.
   4
   5 ## Closing policy for issues and pull requests
   6
   7 Issues and pull requests not in line with the guidelines listed in this document will be closed. GitLab is a popular open source project and the capacity to deal with issues and pull requests is limited. To get support for your problems please use other channels as detailed in [the getting help section of the readme](https://github.com/gitlabhq/gitlabhq#getting-help). Professional [support subscriptions](http://www.gitlab.com/subscription/) and [consulting services](http://www.gitlab.com/consultancy/) are available from [GitLab.com](http://www.gitlab.com/).
   8
   9 ## Issue tracker
  10
  11 The [issue tracker](https://github.com/gitlabhq/gitlabhq/issues) is only for obvious bugs or misbehavior in the latest [stable or development release of GitLab](MAINTENANCE.md). When submitting an issue please conform to the issue submission guidelines listed below.
  12
  13 Do not use the issue tracker for feature requests. We have a specific [feedback and suggestions forum](http://feedback.gitlab.com) for this purpose.
  14
  15 Please send a pull request with a tested solution or a pull request with a failing test instead of opening an issue if you can. If you're unsure where to post, post to the [Support Forum](https://groups.google.com/forum/#!forum/gitlabhq) or [Stack Overflow](http://stackoverflow.com/questions/tagged/gitlab) first. There are a lot of helpful GitLab users there who may be able to help you quickly. If your particular issue turns out to be a bug, it will find its way from there.
  16
  17 ### Issue tracker guidelines
  18
  19 **[Search](https://github.com/gitlabhq/gitlabhq/search?q=&ref=cmdform&type=Issues)** for similar entries before submitting your own, there's a good chance somebody else had the same issue. Show your support with `:+1:` and/or join the discussion. Please submit issues in the following format:
  20
  21 1. **Summary:** Summarize your issue in one sentence (what goes wrong, what did you expect to happen)
  22 2. **Steps to reproduce:** How can we reproduce the issue, preferably on the [GitLab Vagrant virtual machine](https://github.com/gitlabhq/gitlab-vagrant-vm) (start with: `vagrant destroy && vagrant up && vagrant ssh`)
  23 3. **Expected behavior:** Describe your issue in detail
  24 4. **Observed behavior**
  25 5. **Relevant logs and/or screen shots:** Please use code blocks (\`\`\`) to format console output, logs, and code as it's very hard to read otherwise.
  26 6. **Output of checks**
  27     * Results of GitLab [Application Check](doc/install/installation.md#check-application-status) (`sudo -u git -H bundle exec rake gitlab:check RAILS_ENV=production`); we will only investigate if the tests are passing
  28     * Version of GitLab you are running; we will only investigate issues in the latest stable and development releases as per the [maintenance policy](MAINTENANCE.md)
  29     * Add the last commit sha1 of the GitLab version you used to replicate the issue (obtainable from the help page)
  30     * Describe your setup (use relevant parts from `sudo -u gitlab -H bundle exec rake gitlab:env:info`)
  31 7. **Possible fixes**: If you can, link to the line of code that might be responsible for the problem
  32
  33 ## Pull requests
  34
  35 We welcome pull requests with fixes and improvements to GitLab code, tests, and/or documentation. The features we would really like a pull request for are listed with the [status 'accepting merge/pull requests' on our feedback forum](http://feedback.gitlab.com/forums/176466-general/status/796455) but other improvements are also welcome.
  36
  37 ### Pull request guidelines
  38
  39 If you can, please submit a pull request with the fix or improvements including tests. If you don't know how to fix the issue but can write a test that exposes the issue we will accept that as well. The workflow to make a pull request is as follows:
  40
  41 1. Fork the project on GitHub
  42 1. Create a feature branch
  43 1. Write [tests](README.md#run-the-tests) and code
  44 1. If you have multiple commits please combine them into one commit by [squashing them](http://git-scm.com/book/en/Git-Tools-Rewriting-History#Squashing-Commits)
  45 1. Push the commit to your fork
  46 1. Submit a pull request
  47 2. [Search for issues](https://github.com/gitlabhq/gitlabhq/search?q=&ref=cmdform&type=Issues) related to your pull request and mention them in the pull request description
  48
  49 We will accept pull requests if:
  50
  51 * The code has proper tests and all tests pass (or it is a test exposing a failure in existing code)
  52 * It can be merged without problems (if not please use: `git rebase master`)
  53 * It doesn't break any existing functionality
  54 * It's quality code that conforms to the [Rails style guide](https://github.com/bbatsov/rails-style-guide) and best practices
  55 * The description includes a motive for your change and the method you used to achieve it
  56 * It keeps the GitLab code base clean and well structured
  57 * We think other users will benefit from the same functionality
  58 * If it makes changes to the UI the pull request should include screenshots
  59
  60 For examples of feedback on pull requests please look at already [closed pull requests](https://github.com/gitlabhq/gitlabhq/pulls?direction=desc&page=1&sort=created&state=closed).