# 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). **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 (especially bug fixes and new features) MUST include an update to the release notes that clearly describe your changes and the appropriate JIRA key. This will likely mimic your commit message. Don't modify the actual [release-notes file](https://github.com/qos-ch/logback/blob/master/logback-site/src/site/pages/news.html) since this potentially causes a merge conflict. Instead, copy your release notes (in raw HTML) into a comment in the PR, and a logback developer will take care of it. **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) , 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() { ... } public bar() { ... } // good public foo() { ... } public bar() { ... } ```