Commit
This commit does not belong to any branch on this repository, and may belong to a fork outside of the repository.
Added a file to describe general guidelines for submitting pull requests.
- Loading branch information
Showing
1 changed file
with
179 additions
and
0 deletions.
There are no files selected for viewing
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Original file line number | Diff line number | Diff line change |
---|---|---|
@@ -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. | ||
|