# 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 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) , 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() { ... } ```