Newer
Older
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).
**Please note that not every pull-request will be accepted even if it
meets all requirements outlined in this document.**
## 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 of 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 (especially bug fixes) 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!");
}
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
}
```
**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 standalone PR to fix the formatting.
**S8.** No extraneous new-lines. Only one line is necessary between elements.
```java
// bad
public foo() {
...
}