Skip to content

Latest commit

 

History

History
75 lines (66 loc) · 5.75 KB

CONTRIBUTING.md

File metadata and controls

75 lines (66 loc) · 5.75 KB
Raw

General

  • Please do not use the issue tracker to ask questions. This facility is for reporting (and fixing) bugs in the code. If you're not 100% sure it's a bug in the code then please seek help elsewhere. e.g. the jenkins-users google group.
  • RTFM. The Jenkins UI pages include help that should explain things - most fields have online help. The plugin's documentation explains some things in more detail.
  • Be helpful and make no demands.
    • This code is Free Open-Source Software - nobody is obliged to make things work for you but you have legal permission to fix things yourself.
    • If you're reporting and fixing an issue yourself then you only need to explain what problem you're fixing in enough detail that the maintainer(s) can understand why your changes are in the public interest.
    • If you're relying on someone else to fix a problem then you should to make it as easy as possible for others to fix it for you, and you should test any fixes provided.

Legal conditions

  • Any contributions (code, information etc) submitted will be subject to the same license as the rest of the code. No new restrictions/conditions are permitted.
  • As a contributor, you MUST have the legal right to grant permission for your contribution to be used under these conditions.

Reporting a new issue

  • Provide a full description of the issue you are facing.
    • What are you trying to do?
    • How is this failing?
    • What should happen instead?
  • Provide step-by-step instructions for how to reproduce the issue.
  • Specify the Jenkins core & plugin version you're seeing the issue with.
  • Check Manage Jenkins -> Manage Old Data for out of date configuration data and provide this info.
  • Check for and include output from Manage Jenkins -> System Log.
    • If that log is too verbose, create a vSphere log as described in the "Debugging" section of the docs.
    • Exceptions and stacktraces are especially useful, so don't omit those...
    • Note that sensitive information may be visible in logs, so take care to redact logs where necessary.
  • The reported activity & results from your vSphere system may also be relevant.
    • When providing logs from multiple sources, please ensure that all logs are from the same time period and clocks are in sync.
  • Provide a copy/paste of the Cloud section from $JENKINS_HOME/config.xml file (redacted where neccessary).
  • Describe your vSphere system (the way that's configured can make a big difference to how things work).
  • Ensure that any code or log example surround with right markdown otherwise it'll be unreadable.

Submitting pull requests

  • A PR's description must EITHER refer to an existing issue (either in github or on Jenkins JIRA) OR include a full description as for "Creating new issue".
  • A single PR should EITHER be making functional changes OR making (non-functional) cosmetic/refactoring changes to the code. Please do not do both in the same PR as this makes life difficult for anyone else merging your changes.
  • For functional-change PRs, keep changes to a minimum (to make merges easier).
  • Coding style:
    • Try to fit in. Not all of the code within this plugin is written in the same "style". Any changes you make must fit in with the existing style that is prevalent within the area in which you are working. i.e. code in the same style that the existing method/class/package uses.
    • If you can't tolerate inconsistencies, submit a cosmetic PR that applies the formatting/whitespace/non-functional changes that you want made.
    • If in doubt, use 4 spaces for indentation, avoid using tabs, avoid trailing whitespace, use unix end-of-line codes (LF, not CR/LF), and make sure every file ends with a newline.
  • Unit tests:
    • Any new functionality should be unit tested if at all possible ... but not rely on the presence of a vSphere system to talk to.
    • PRs that add unit-tests for existing functionality will be very welcome too.
    • Unit tests should be as fast as possible but must be reliable (Tests that behave inconsistently cause trouble for everyone else trying to work on the code).
  • Clean build & test:
    • Any submitted PRs should automatically get built and tested; PRs will not be considered for merger until they are showing a clean build. If you believe that the build failed for reasons unconnected to your changes, close your PR, wait 10 minutes, then re-open it (just re-open the same PR; don't create a new one) to trigger a rebuild. Repeat until it builds clean, changing your code if necessary.
    • Please provide unit-tests for your contribution.
    • Don't give findbugs, the compiler or any IDEs anything new to complain about.
  • Preserve existing functionality by default:
    • Where possible, ensure that existing users don't find that their functionality has changed after they've upgraded from an old version of the plugin to a version of the plugin that contains your changes.
    • When adding new functionality, try to keep the defaults are unchanged so that nobody finds new, unexpected, things happening after upgrading.
    • Ensure any breaking changes are well documented in the PR description.
  • Configuration data changes:
    • If the PR adds a new field to an existing (or new) data structure, make sure you've written good help text for it that explains what it's for, why it's useful, and an example. Implement corresponding doCheck methods to provide validation when users are entering this data from the WebUI.
    • If the PR changes an existing field, make sure that the code copes with reading in data from older versions of the plugin.

Links