CONTRIBUTING.md (6054B)
1 # Contributing to libjxl 2 3 ## Contributing with bug reports 4 5 For security-related issues please see [SECURITY.md](SECURITY.md). 6 7 We welcome suggestions, feature requests and bug reports. Before opening a new 8 issue please take a look if there is already an existing one in the following 9 link: 10 11 * https://github.com/libjxl/libjxl/issues 12 13 ## Contributing with patches and Pull Requests 14 15 We'd love to accept your contributions to the JPEG XL Project. Please read 16 through this section before sending a Pull Request. 17 18 ### Contributor License Agreements 19 20 Our project is open source under the terms outlined in the [LICENSE](LICENSE) 21 and [PATENTS](PATENTS) files. Before we can accept your contributions, even for 22 small changes, there are just a few small guidelines you need to follow: 23 24 Please fill out either the individual or corporate Contributor License Agreement 25 (CLA) with Google. JPEG XL Project is an an effort by multiple individuals and 26 companies, including the initial contributors Cloudinary and Google, but Google 27 is the legal entity in charge of receiving these CLA and relicensing this 28 software: 29 30 * If you are an individual writing original source code and you're sure you 31 own the intellectual property, then you'll need to sign an [individual 32 CLA](https://code.google.com/legal/individual-cla-v1.0.html). 33 34 * If you work for a company that wants to allow you to contribute your work, 35 then you'll need to sign a [corporate 36 CLA](https://code.google.com/legal/corporate-cla-v1.0.html). 37 38 Follow either of the two links above to access the appropriate CLA and 39 instructions for how to sign and return it. Once we receive it, we'll be able 40 to accept your pull requests. 41 42 ***NOTE***: Only original source code from you and other people that have signed 43 the CLA can be accepted into the main repository. 44 45 ### License 46 47 Contributions are licensed under the project's [LICENSE](LICENSE). Each new 48 file must include the following header when possible, with comment style adapted 49 to the language as needed: 50 51 ``` 52 // Copyright (c) the JPEG XL Project Authors. All rights reserved. 53 // 54 // Use of this source code is governed by a BSD-style 55 // license that can be found in the LICENSE file. 56 ``` 57 58 ### Code Reviews 59 60 All submissions, including submissions by project members, require review. We 61 use GitHub pull requests for this purpose. Consult 62 [GitHub Help](https://help.github.com/articles/about-pull-requests/) for more 63 information on using pull requests. 64 65 ### Contribution philosophy 66 67 * Prefer small changes, even if they don't implement a complete feature. Small 68 changes are easier to review and can be submitted faster. Think about what's 69 the smallest unit you can send that makes sense to review and submit in 70 isolation. For example, new modules that are not yet used by the tools but 71 have their own unittests are ok. If you have unrelated changes that 72 you discovered while working on something else, please send them in a 73 different Pull Request. If your are refactoring code and changing 74 functionality try to send the refactor first without any change in 75 functionality. Reviewers may ask you to split a Pull Request and it is 76 easier to create a smaller change from the beginning. 77 78 * Describe your commits. Add a meaningful description to your commit message, 79 explain what you are changing if it is not trivially obvious, but more 80 importantly explain *why* you are making those changes. For example "Fix 81 build" is not a good commit message, describe what build and if it makes sense 82 why is this fixing it or why was it failing without this. It is very likely 83 that people far in the future without any context you have right now will be 84 looking at your commit trying to figure out why was the change introduced. If 85 related to an issue in this or another repository include a link to it. 86 87 * Code Style: We follow the [Google C++ Coding 88 Style](https://google.github.io/styleguide/cppguide.html). A 89 [clang-format](https://clang.llvm.org/docs/ClangFormat.html) configuration 90 file is available to automatically format your code, you can invoke it with 91 the `./ci.sh lint` helper tool. 92 93 * Testing: Test your change and explain in the commit message *how* your 94 commit was tested. For example adding unittests or in some cases just testing 95 with the existing ones is enough. In any case, mention what testing was 96 performed so reviewers can evaluate whether that's enough testing. In many 97 cases, testing that the Continuous Integration workflow passes is enough. 98 99 * Make one commit per Pull Request / review, unless there's a good reason not 100 to. If you have multiple changes send multiple Pull Requests and each one can 101 have its own review. 102 103 * When addressing comments from reviewers prefer to squash or fixup your 104 edits and force-push your commit. When merging changes into the repository we 105 don't want to include the history of code review back and forth changes or 106 typos. Reviewers can click on the "force-pushed" automatic comment on a Pull 107 Request to see the changes between versions. We use "Rebase and merge" policy 108 to keep a linear git history which is easier to reason about. 109 110 * Your change must pass the build and test workflows. There's a `ci.sh` script 111 to help building and testing these configurations. See [building and 112 testing](doc/building_and_testing.md) for more details. 113 114 ### Contributing checklist. 115 116 * Sign the CLA (only needed once per user, see above). 117 118 * AUTHORS: You can add your name to the [AUTHORS](AUTHORS) file. 119 120 * Style guide. Check `./ci.sh lint`. 121 122 * Meaningful commit description: What and *why*, links to issues, testing 123 procedure. 124 125 * Squashed multiple edits into a single commit. 126 127 * Upload your changes to your fork and [create a Pull 128 Request](https://docs.github.com/en/github/collaborating-with-issues-and-pull-requests/proposing-changes-to-your-work-with-pull-requests/creating-a-pull-request). 129 130 # Community Guidelines 131 132 This project follows [Google's Open Source Community 133 Guidelines](https://opensource.google.com/conduct/).