Skip to content

Commit

Permalink
Add CONTRIBUTING.md
Browse files Browse the repository at this point in the history
Added a file to describe general guidelines for submitting pull requests.
  • Loading branch information
tony19 committed Mar 30, 2014
1 parent 9a1330d commit c088346
Showing 1 changed file with 179 additions and 0 deletions.
179 changes: 179 additions & 0 deletions CONTRIBUTING.md
@@ -0,0 +1,179 @@
# Bug reports / Github pull-requests

When reporting a bug or submitting a pull request, make sure you search
[JIRA](http://jira.qos.ch/browse/LOGBACK) and
[GitHub pull requests](https://github.com/qos-ch/logback/pulls)
for the same/similar issues. If you find one, feel free to add a `+1` comment
with any additional information that may help us solve the issue.

When creating a new bug report, be sure to state the following:

* Detailed steps to reproduce the bug
* The version of logback and SLF4J you are using
* Operating system and its version, any other relevant environment details


# Submitting a pull-request

## Before you begin
Is this the right place for the PR?

YES:
* If it's a **bug fix** for logback proper (`logback-core`,
`logback-classic`, `logback-access`)
* If it's a **new feature** (such as an appender), and you're willing to
submit a [signed CLA](http://logback.qos.ch/cla.txt)

NO:
* If it's a **new feature**, but you prefer not to submit a signed CLA
* If it's a **new feature**, and you wish to see it released sooner than
logback's release schedule

If your PR falls into the *NO* category, please submit it to either
[`logback-extensions`](https://github.com/qos-ch/logback-extensions)
(no CLA required, shorter release cycles than logback, Apache License)
or [`logback-contrib`](https://github.com/qos-ch/logback-contrib)
(CLA required, shorter release cycles than logback, same license as logback).

## Instructions
1. [Fork](https://help.github.com/articles/fork-a-repo) the repo on GitHub.
2. Make a [topic branch](https://github.com/dchelimsky/rspec/wiki/Topic-Branches#using-topic-branches-when-contributing-patches)
and start hacking.
3. If your branch becomes several commits behind master, be sure to rebase
to avoid a merge conflict.
3. Submit a pull-request based off your topic branch, following the patch
rules below.
4. If your patch is non-trivial and you haven't submitted a [signed CLA](http://logback.qos.ch/cla.txt),
please email it to ceki@qos.ch and tony19@gmail.com with **\[logback]
signed CLA** in the subject line. Trivial bug fixes (less than ~30 lines)
do not require a CLA.

## Patch rules

**P1.** The patch MUST follow the [general logback code style](General style notes).
Disable your IDE's auto-formatting for logback files (unless you're using
the logback [`codeStyle.xml`](https://github.com/qos-ch/logback/blob/master/codeStyle.xml)
file in Eclipse).

**P2.** Small focused patches are preferred. The patch MUST NOT mix new features
and bug fixes in the same pull-request. Also exclude reformatting from
the pull-request (move that to its own commit or another pull-request).

**P3.** Large changes to the code SHOULD be discussed with the core team first.
Create an issue, explaining your plan, and see what we say.

**P4.** The commit message SHOULD be formatted as described in http://tbaggery.com/2008/04/19/a-note-about-git-commit-messages.html
and indicate the appropriate JIRA key.

**P5.** Pull-requests MUST NOT contain intermediate commits (e.g., bug fixes to
your own patch, refactoring your own patch), which should be [squashed and
then force-pushed to your branch](https://github.com/edx/edx-platform/wiki/How-to-Rebase-a-Pull-Request).
Fewer commits are better.

**P6.** Unit tests MUST be included for behavioral changes or new features.

**P7.** Pull-requests MUST include an update in the release notes that clearly
describe your changes and the appropriate JIRA key. This will likely
mimic your commit message.

**P8.** Pull-requests MUST include updates to logback's documentation pages,
where necessary. Examples where this would be required:
* adding/removing a configuration flag to `SyslogAppender`
* adding a new appender to `logback-classic`

# General style notes

Please note that most of the formatting rules are provided in
[codeStyle.xml](https://github.com/qos-ch/logback/blob/master/codeStyle.xml)
in the root directory of logback.

> **When in Rome, code like the Romans do**.
**S1.** Use 2-space indents.

```java
// bad
class Foo {
public static void main(String[] args) {
System.out.println("hello world!");
}
}

// good
class Foo {
public static void main(String[] args) {
System.out.println("hello world!");
}
}
```

**S2.** Closing-curly bracket should be on its own line. Opening-curly bracket
should not.

```java
// bad
if (foo)
{
...
}

// bad
if (foo)
{ ... }

// bad
if (foo) {
... }

// good
if (foo) {
...
}
```

**S3.** Delimit keywords and brackets with a space.

```java
// bad
try{
...
}catch(Exception e){
...
}

// good
try {
...
} catch (Exception e) {
...
}
```

**S4.** Add logback's standard file-header to any new files.

```java
/**
* Logback: the reliable, generic, fast and flexible logging framework.
* Copyright (C) <year>, QOS.ch. All rights reserved.
*
* This program and the accompanying materials are dual-licensed under
* either the terms of the Eclipse Public License v1.0 as published by
* the Eclipse Foundation
*
* or (per the licensee's choosing)
*
* under the terms of the GNU Lesser General Public License version 2.1
* as published by the Free Software Foundation.
*/
```

**S5.** Add javadoc for public functions (we won't fault you for skipping private
functions unless comments are warranted).

**S6.** Code for maintainability. We would rather a function be a couple of lines
longer and have (for example) some [explaining variables](http://www.refactoring.com/catalog/extractVariable.html)
to aid readability.

**S7.** If you find that a file has two different styles in use, defer to the
standard style notes here. You can submit a PR to only fix the formatting.

0 comments on commit c088346

Please sign in to comment.