diff --git a/.github/CONTRIBUTING.md b/.github/CONTRIBUTING.md index d1dca44b426..758d11a3d6a 100644 --- a/.github/CONTRIBUTING.md +++ b/.github/CONTRIBUTING.md @@ -1,32 +1,132 @@ -# Contributing +# Contribution Guidelines ![](https://raw.githubusercontent.com/checkstyle/resources/master/img/checkstyle-logos/checkstyle-logo-260x99.png) -* [Reporting issues](https://checkstyle.org/report_issue.html) -* [How to report a bug?](https://checkstyle.org/report_issue.html#How_to_report_a_bug.3F) -* [Issue Template](https://github.com/checkstyle/checkstyle/blob/master/.github/ISSUE_TEMPLATE/bug_report.md) +--------------------------------- -Please provide issue report in the format that we request, EACH DETAIL IS A HUGE HELP. +**This guide serves to set clear expectations for everyone involved with the project so that +we can improve it together while also creating a welcoming space for everyone to participate. +Following these guidelines will help ensure a positive experience for contributors and +maintainers alike.** -Issues that are not following the guidelines, -will be processed as last priority or never or simply closed as invalid. +:octocat: *Thanks for your interest in contributing to CheckStyle!* :octocat: -## Contributing Guide +## Contents -Please note that PRs are looked only for approved issues. Follow the PR guide for opening a PR +- [Code of Conduct](#code-of-conduct) +- [Getting Started](#getting-started) +- [Opening an Issue](#opening-an-issue) +- [Reporting Security Issues](#reporting-security-issues) +- [Submitting Pull Requests](#submitting-pull-requests) +- [Code Review](#code-review) +- [Google Summer of Code](#google-summer-of-code) +- [Asking Questions](#asking-questions) +- [Credits](#credits) -* [Pull Request Template](https://github.com/checkstyle/checkstyle/blob/master/.github/PULL_REQUEST_TEMPLATE.md) +## Code of Conduct -Please follow the below links in order to start contributing to the checkstyle project +This project and everyone participating in it is governed by the + [CheckStyle Code of Conduct](/.github/CODE_OF_CONDUCT.md). -* [Beginning Development](https://checkstyle.org/beginning_development.html) +## Getting Started -* [Contribution Guidelines](https://checkstyle.org/contributing.html) +- Please see the [CheckStyle Documentation](https://checkstyle.org/beginning_development.html) + for information on how to get started with the project. This includes setting up your + development environment, building the project, and running tests. +- Take a look at the [Contribution Guidelines](https://checkstyle.org/contributing.html) for + on how to contribute to the project. +- Select an issue to work on from the + [Issues Page](https://github.com/checkstyle/checkstyle/issues). We + have a few issues labeled as + https://github.com/checkstyle/checkstyle/labels/good%20first%20issue to + help you get started. Once you get your first PR merged, you can move on to + https://github.com/checkstyle/checkstyle/labels/good%20second%20issue, + https://github.com/checkstyle/checkstyle/labels/good%20third%20issue, + and finally https://github.com/checkstyle/checkstyle/labels/good%20fourth%20issue + before taking up some bug fixes or features. Always make sure that the issue you select + has the https://github.com/checkstyle/checkstyle/labels/approved label. -Find the links below to import the checkstyle project to an IDE +## Opening an Issue -* [Importing checkstyle project to IntelliJ](https://checkstyle.org/idea.html) +A great way to contribute to the project is to create a detailed issue when you encounter +a problem or would like to suggest a feature. We always appreciate a well-written, +thorough issue description. :brain: -* [Importing checkstyle project to Eclipse](https://checkstyle.org/eclipse.html) +Some points to consider when opening an issue: -* [Importing checkstyle project to Netbeans](https://checkstyle.org/netbeans.html) +- **Make sure you are using the latest Checkstyle version.** + Before [Opening an Issue](https://github.com/checkstyle/checkstyle/issues), + check if you are using the latest version of the project, + [found here](https://github.com/checkstyle/checkstyle/releases). If you are not up-to-date, + check to see if updating to the latest release fixes your issue. +- **Do not open a duplicate feature request.** Search for existing feature requests first. If you + find your feature (or one very similar) previously requested, comment on that issue. +- **Fully complete the provided issue template.** The bug report and feature request templates + specify all the information we need to quickly and efficiently address your issue. Be clear, + concise, and descriptive. + Provide as much information as you can, including steps to reproduce, stack traces, etc. +- **Use [GitHub-flavored Markdown](https://help.github.com/en/github/writing-on-github/basic-writing-and-formatting-syntax).** + Especially put code blocks and console outputs in backticks (```). This improves readability. + +## Reporting Security Issues + +**Do not file a public issue for security vulnerabilities.** Please contact the +maintainers directly. +see the [Security Policy](https://github.com/checkstyle/checkstyle/blob/master/SECURITY.md) +for more information. + +## Submitting Pull Requests + +- **Read our pull request rules.** See [PR Rules](https://github.com/checkstyle/checkstyle/wiki/PR-rules). +- **Comment on the issue.** When you decide which issue you would like to take up, + please comment on the issue to let others know that you are working on it ("I am on it."). + Existing "I am on it" comments are a good indication that someone is already working on the + issue, but these comments can be old or outdated; if a comment is a few weeks old with no + activity, feel free to ask if the issue is still being worked on. +- **Read the Github docs.** Visit GitHub's [Pull Request Guide](https://help.github.com/en/github/collaborating-with-issues-and-pull-requests/about-pull-requests) + for information on how to submit a pull request. +- **Follow the template.** Please follow the [CheckStyle Pull Request Template](https://github.com/checkstyle/checkstyle/blob/master/.github/PULL_REQUEST_TEMPLATE.md) + that is provided in the pull request description when submitting a pull request. +- **Run maven build locally.** `mvn clean verify` should pass on your local before + submitting a pull request. +- **Keep the PR small.** If you are working on a large feature, consider breaking it up into + smaller PRs that can be reviewed and merged independently. This makes it easier for + reviewers to understand the changes and for maintainers to merge the PR. + +## Code Review + +All submissions, including submissions by project members, require review. We use GitHub pull +requests for this purpose. Consult the [GitHub Help](https://help.github.com/en/github/collaborating-with-issues-and-pull-requests/about-pull-request-reviews) +for more information on pull request reviews. + +Here are some general guidelines to follow when submitting a pull request: + +- **Reply to comments.** If a reviewer asks for changes, reply to each + (and every) comment with discussion or follow up questions, or let the reviewer know + that you have addressed their concerns ("done"). +- **Be patient.** Reviewing PRs takes time. If a reviewer hasn't responded in a week or so, + feel free to ping them. If you are a reviewer and you need more time to review a PR, please + let the submitter know. +- **Be kind.** Remember that everyone involved in the project is a human being. Be kind and + respectful in your comments and reviews. +- **Be open to feedback.** If a reviewer asks for changes, be open to their feedback. Remember that + the goal is to improve the project, and feedback is an important part of that process. + +## Google Summer of Code + +Please see the [GSoC Participant Guide](https://github.com/checkstyle/checkstyle/blob/master/.github/GSOC.md). + +## Asking Questions + +See our [Discussions Page](https://github.com/checkstyle/checkstyle/discussions). In short, GitHub +issues are not the appropriate place to debug your specific project, but should be reserved +for filing bugs and feature requests. You can also visit our +[Google Groups Forum](https://groups.google.com/g/checkstyle-devel) + +## Credits + +*This document was inspired by work from the following communities:* + +- [CocoaPods](https://github.com/CocoaPods/CocoaPods/blob/master/CONTRIBUTING.md) +- [Docker](https://github.com/moby/moby/blob/master/CONTRIBUTING.md) +- [.github](https://github.com/jessesquires/.github) diff --git a/.github/GSOC.md b/.github/GSOC.md new file mode 100644 index 00000000000..917949779c0 --- /dev/null +++ b/.github/GSOC.md @@ -0,0 +1,125 @@ +# GSOC Participant Guide + +![](https://raw.githubusercontent.com/checkstyle/resources/master/img/checkstyle-logos/checkstyle-logo-260x99.png) + +--------------------------------- + +**This guide serves to set clear expectations and provide guidance for Google Summer of Code (GSoC) +participants.** + +:sun_with_face: Thanks for your interest in participating in GSoC with Checkstyle! :sun_with_face: + +## Contents + +- [Getting Started](#getting-started) +- [Additional Tips](#additional-tips) +- [Your Proposal](#your-proposal) + +## Getting Started + +Thanks for your interest in participating in GSoC with Checkstyle! Joining Checkstyle for the summer +is a great way to learn about open source software development and contribute to a widely-used +project. We are excited to work with you and help you grow as a software developer. You don't +need to be an expert in Java or Checkstyle to participate. We are looking for participants who are +eager to learn, work hard, and are excited to contribute to open source software. Additionally, we +want you to stick around after GSoC and become a long-term member of our community :smile:. + +Please take the time to read through this guide and familiarize yourself with the project. If you +have any questions, please don't hesitate to ask. We are here to help you succeed. If you have +not already done so, please read through the following documentation provided by Google: + +- [GSoC Participant Guide](https://summerofcode.withgoogle.com/rules/). +- [GSoC FAQ](https://developers.google.com/open-source/gsoc/faq). + +### Recommended Steps + +- **Get to know the project.** Spend some time reading through the Checkstyle documentation and + familiarizing yourself with the project. You can find the documentation at + [https://checkstyle.org/](https://checkstyle.org/). +- **Join the Checkstyle community.** + Join the Checkstyle group on [Gitter](https://gitter.im/checkstyle/checkstyle). + This is a great place to ask questions and get to know the community. + Join the Checkstyle group on [Google Groups](https://groups.google.com/forum/#!forum/checkstyle). + This is another place to ask questions and get to know the community. +- **Start contributing.** We have a list of issues labeled as + https://github.com/checkstyle/checkstyle/labels/good%20first%20issue. These are a great place to + start. Once you complete a few of these, you will have a better understanding of the project and + be ready to move on to https://github.com/checkstyle/checkstyle/labels/good%20second%20issue, + and so on. Once you have completed a few of these, you will be ready to start working on some + more challenging issues, like bug fixes and new features. +- **Take a Look at Our Project Ideas.** We have a list of project ideas that we think would be + great for GSoC. You can find them in our wiki [Checkstyle Wiki](https://github.com/checkstyle/checkstyle/wiki). + You can also propose your own project idea. We are open to new ideas and would love to hear + what you are interested in working on. +- **Create a Draft Proposal.** Once you have a good understanding of the project and have an idea + of what you would like to work on, create a draft proposal. We are happy to help you refine your + proposal and provide feedback. The best way to share your draft proposal is through Google docs. +- **Submit Your Proposal.** Now that you have refined your proposal, submit it through the + GSoC website **before the final submission deadline**. + +## Additional Tips + +- **Start Early.** The earlier you start, the more time you will have to get to know the project, + accumulate contributions, and refine your proposal. +- **Communicate Effectively.** We are looking for participants who can communicate effectively. This + includes using clear and concise language, being responsive to feedback, and being proactive. +- **Contribute, Contribute, Contribute.** This is the single best way to show us that you are + serious becoming a valuable member of our community. + +## Your Proposal + +Your proposal is your opportunity to show us that you are the right person for the job. To this end, +we have provided a list of things that we would like to see in your proposal. We are not looking for +a long proposal, but we are looking for a well-thought-out proposal that shows us that you have +taken the time to understand the project and have a clear plan for how you will contribute. + +### Proposal Outline + +#### Introduction + +All projects aim to solve a problem or improve something. Start your proposal by introducing the +problem you are trying to solve or the improvement you are trying to make. This is your opportunity +to show us that you understand the problem, why it is important, and why it is worth solving. +Include any relevant background information that will help us understand the problem, like +statistics, examples, references to existing issues, etc. + +#### Project Goals + +This should be concise and to the point. What are you trying to accomplish? What are the +deliverables? What are the success criteria? What are the key milestones? Effective goals are +specific, measurable, and achievable. This section may be a bulleted list or outline. + +#### Implementation Plan + +Describe your solution to the problem. This should include a high-level overview of the +architecture, a list of tasks, and a list of potential challenges, as well as some technical +details. We want to see that you have thought through the problem and can visualize how you will +solve it. + +#### Timeline + +Show us that you can break down your project into manageable tasks and that you have a clear plan +for how you will accomplish your goals. This should be a timeline that shows what you will be +working on each week. It should include milestones and deliverables. An effective way to present +this is in a table. + +#### About You + +Tell us about yourself. what time zone are you located in? +What is your background? What are your interests? +What are your career goals? +This is your opportunity to show us that you are a good fit for the project and that +you are excited to work with us. **You must include a list of links to your Checkstyle contributions +to be considered for GSoC; this is one of the most important selection criteria.** + +### Proposal Tips + +- Be Specific. We want to see that you have thought through the problem and + how you will solve it. +- Be Realistic. We are looking for a proposal that is achievable in the time frame of GSoC. + We want to see that you have a clear plan. +- Be Professional. We are looking for a proposal that is well-written and professional. +- One Proposal <-> One Project. Do not create a proposal that spans multiple projects. +- Proposal Title. If creating a proposal based on our project ideas, please use the title of the + project idea as the title of your proposal. If you are proposing your own project idea, please + create a title that is descriptive and concise. diff --git a/README.md b/README.md index 82305ca4851..4af31c2d1a8 100644 --- a/README.md +++ b/README.md @@ -1,7 +1,10 @@ -# ![](https://raw.githubusercontent.com/checkstyle/resources/master/img/checkstyle-logos/checkstyle-logo-260x99.png) +# Checkstyle - Java Code Quality Tool -Checkstyle is a tool for checking Java source code for adherence to a Code Standard -or set of validation rules (best practices). +![](https://raw.githubusercontent.com/checkstyle/resources/master/img/checkstyle-logos/checkstyle-logo-260x99.png) + +-------------------------- + +*Checkstyle is a tool that ensures adherence to a code standard or a set of best practices.* [![][travis img]][travis] [![][appveyor img]][appveyor] @@ -14,17 +17,12 @@ or set of validation rules (best practices). [![][error prone img]][error prone] [![][pitest img]][pitest] [![][checker framework img]][checker framework] - [![][dependabot img]][dependabot] - [![][mavenbadge img]][mavenbadge] [![][sonar img]][sonar] - [![][release notes/version img]][release notes/version] - [![][closed issues img]][closed issues] [![][link check img]][link check] - [![][milestone img]][milestone] The latest release version can be found at @@ -36,71 +34,109 @@ Each-commit builds of maven artifacts can be found at Documentation is available in HTML format, see https://checkstyle.org/checks.html . -## Build instructions and Contribution - -[Build instructions](https://checkstyle.org/contributing.html#Build) - -[Setup IDE for development](https://checkstyle.org/beginning_development.html) - -[Explanation on how to create your own module](https://checkstyle.org/extending.html) - -[Verification of code quality](https://checkstyle.org/contributing.html#Quality_matters) - -[Sending Pull Request](https://checkstyle.org/contributing.html#Submitting_your_contribution) - -[Report Issue](https://checkstyle.org/contributing.html#Report_an_issue) - -## Continuous integration and Quality reports - -See our CIs statuses. - -Quality reports: https://checkstyle.org/project-reports.html - -JavaScript, CSS and Java source file analysis on Codacy: [![][codacy img]][codacy] +## Table of Contents + +- [Quick Start](#quick-start) +- [Contributing](#contributing) +- [Feedback and Support](#feedback-and-support) +- [Javadoc](#javadoc) +- [Sponsor Checkstyle](#sponsor-checkstyle) +- [Licensing](#licensing) + +## Quick Start + +- Download our [Latest Release](https://github.com/checkstyle/checkstyle/releases/) from GitHub + or Add Checkstyle to your build from [Maven Central](https://mvnrepository.com/artifact/com.puppycrawl.tools/checkstyle). +- Read our Documentation for [usage](https://checkstyle.org/cmdline.html) + and [configuration](https://checkstyle.org/config.html). + +```bash +$ cat config.xml + + + + + + + + +$ cat Test.java +class Test { + public void foo() { + int i = 0; + while (i >= 0) { + switch (i) { + case 1: + case 2: + i++; + case 3: // violation 'fall from previous branch of the switch' + i++; + } + } + } +} + +$ java -jar checkstyle-10.18.1-all.jar -c config.xml Test.java +Starting audit... +[ERROR] Test.java:9:9: Fall through from previous branch of the switch statement. [FallThrough] +Audit done. +Checkstyle ends with 1 errors. +``` + +## Contributing + +Thanks for your interest in contributing to CheckStyle! Please see the +[Contribution Guidelines](https://github.com/checkstyle/checkstyle/blob/master/.github/CONTRIBUTING.md) +for information on how to contribute to the project. This includes creating issues, submitting pull +requests, and setting up your development environment. + +## Build Instructions + +Please see the [CheckStyle Documentation](https://checkstyle.org/contributing.html#Build) for +information on how to build the project. + +## Feedback and Support + +- Visit our [Discussions Page](https://github.com/checkstyle/checkstyle/discussions), where you + can ask questions and discuss the project with other users and contributors. This is our + preferred method of communication for topics + like usage and configuration questions, debugging, and other feedback. +- [Stack Overflow](https://stackoverflow.com/questions/tagged/checkstyle) is another place to + ask questions about Checkstyle usage. +- If you are interested in contributing to the project, you can join our + [Discord Contributors Chat](https://discord.com/channels/845645228467159061/1216455699488313554). +- Our [Google Groups Forum](https://groups.google.com/forum/?hl=en#!forum/checkstyle) is a + mailing list for discussion and support; however, we may be slow to respond there. + +## Javadoc + +Take a look at our [javadoc](https://checkstyle.org/apidocs/index.html) to see +our API documentation. + +## Sponsor Checkstyle + +Checkstyle is an open-source project that is developed and maintained by volunteers. If you +find Checkstyle useful, please consider sponsoring the project. Your support helps us to +maintain and improve Checkstyle. + +- [Liberapay](https://liberapay.com/checkstyle/) +- [OpenCollective](https://opencollective.com/checkstyle/) -## Feedback/Support - -Please send any feedback to https://groups.google.com/forum/?hl=en#!forum/checkstyle - -Questions and Answers from community: [![][stackoverflow img]][stackoverflow] - -Bugs and Feature requests (not the questions): https://github.com/checkstyle/checkstyle/issues - -## Support/Sponsor checkstyle - -If you want to speed up fixing of issue and want to encourage somebody in -internet to resolve any issue: -[![][flattr img]][flattr] -[![][liberapay img]][liberapay] [![][backers.opencollective img]][backers.opencollective] + [![][sponsors.opencollective img]][sponsors.opencollective] ## Licensing -[![][license img]][license] - -This software is licensed under the terms in the file named "LICENSE" in this -directory. - -The software uses the ANTLR package (https://www.antlr.org/). Its license terms -are in the file named "RIGHTS.antlr" in this directory. +Checkstyle is licensed under the [GNU LGPL v2.1 License](LICENSE). +Checkstyle uses libraries: -This product includes software developed by -The Apache Software Foundation (https://www.apache.org/). - -The software uses the Logging and Beanutils packages from the -Apache Commons project (https://commons.apache.org/). The license terms -of these packages are in the file named "LICENSE.apache20" in this -directory. - -The software uses the Google Guava Libraries -(https://github.com/google/guava/). The license terms of -these packages are in the file named "LICENSE.apache20" in this -directory. - -The software uses the Picocli Library -(https://github.com/remkop/picocli/). Its license terms -are in the file named "LICENSE.apache20" in this directory. +- [ANTLR](https://www.antlr.org/) +- [Apache Commons](https://commons.apache.org/) +- [Google Guava](https://github.com/google/guava/) +- [Picocli](https://github.com/remkop/picocli/) [travis]:https://travis-ci.com/github/checkstyle/checkstyle/builds [travis img]:https://api.travis-ci.com/checkstyle/checkstyle.svg @@ -111,21 +147,12 @@ are in the file named "LICENSE.apache20" in this directory. [sonar]:https://sonarcloud.io/dashboard?id=org.checkstyle%3Acheckstyle [sonar img]:https://sonarcloud.io/api/project_badges/measure?project=org.checkstyle%3Acheckstyle&metric=sqale_index -[codacy]:https://www.codacy.com/app/checkstyle/checkstyle -[codacy img]:https://api.codacy.com/project/badge/3adf12d434314ba8b38277ea46d3c44b - [coverage]:https://codecov.io/github/checkstyle/checkstyle?branch=master [coverage img]:https://codecov.io/github/checkstyle/checkstyle/coverage.svg?branch=master -[license]:LICENSE -[license img]:https://img.shields.io/badge/license-GNU%20LGPL%20v2.1-blue.svg - [mavenbadge]:https://search.maven.org/search?q=g:%22com.puppycrawl.tools%22%20AND%20a:%22checkstyle%22 [mavenbadge img]:https://img.shields.io/maven-central/v/com.puppycrawl.tools/checkstyle.svg?label=Maven%20Central -[matrix_con]:https://app.element.io/#/room/#checkstyle_checkstyle:gitter.im -[matrix_con img]:https://matrix.to/img/matrix-badge.svg - [stackoverflow]:https://stackoverflow.com/questions/tagged/checkstyle [stackoverflow img]:https://img.shields.io/badge/stackoverflow-CHECKSTYLE-blue.svg @@ -144,15 +171,9 @@ are in the file named "LICENSE.apache20" in this directory. [semaphoreci]: https://checkstyle.semaphoreci.com/projects/checkstyle [semaphoreci img]: https://checkstyle.semaphoreci.com/badges/checkstyle/branches/master.svg?style=shields -[flattr]:https://flattr.com/submit/auto?fid=g39d10&url=https%3A%2F%2Fcheckstyle.org -[flattr img]:https://button.flattr.com/flattr-badge-large.png - [azure]:https://dev.azure.com/romanivanovjr/romanivanovjr/_build/latest?definitionId=1&branchName=master [azure img]:https://dev.azure.com/romanivanovjr/romanivanovjr/_apis/build/status/checkstyle.checkstyle?branchName=master -[liberapay]:https://liberapay.com/checkstyle/ -[liberapay img]:https://liberapay.com/assets/widgets/donate.svg - [backers.opencollective]:https://opencollective.com/checkstyle/ [backers.opencollective img]:https://opencollective.com/checkstyle/backers/badge.svg diff --git a/config/jsoref-spellchecker/whitelist.words b/config/jsoref-spellchecker/whitelist.words index a78be45f79e..422af0c12e9 100644 --- a/config/jsoref-spellchecker/whitelist.words +++ b/config/jsoref-spellchecker/whitelist.words @@ -16,7 +16,6 @@ acm Aconfig actionlint addons -adf admins adr AFilter @@ -90,7 +89,7 @@ awt azurewebsites backport Backquote -Backticks +backticks BADN badpackage baeldung @@ -519,6 +518,8 @@ groovyism groupcdg groupon grp +GSo +gsoc Gsp GString Gtk @@ -682,6 +683,7 @@ jdt jedit jenkins jep +jessesquires jetbrains JFile JFrame @@ -834,6 +836,7 @@ mixin mkdir mkordas MLINKCHECK +moby mockit mockito modifiedcontrolvariable @@ -859,6 +862,7 @@ mutableexception mutationtest MVC mvn +mvnrepository mvnw Mycheckstyle mycompany @@ -960,6 +964,7 @@ OAuth objblock oburn OCP +octocat ogg OI olddomain @@ -1271,6 +1276,7 @@ sudo suitebuilder sukhodolsky summaryjavadoc +summerofcode superclasses superclone superfinalize @@ -1322,6 +1328,7 @@ throwable throwscount Thymeleaf tidelift +timeline TKN Tls tmp @@ -1448,6 +1455,7 @@ wiki wikipedia wiktionary windowsservercore +withgoogle wnd WOC woff diff --git a/src/xdocs/contributing.xml b/src/xdocs/contributing.xml index 08eda7a123b..fe23d6ca3d4 100644 --- a/src/xdocs/contributing.xml +++ b/src/xdocs/contributing.xml @@ -73,14 +73,14 @@

- Generate maven standard jar: mvn install + Generate maven standard jar: mvn clean install
Generate maven standard jar and skip all validations/verifications: - mvn -P no-validations install + mvn -P no-validations clean install
Generate uber jar (checkstyle-all-X.XX.jar) to use our command line: - mvn -P assembly package + mvn -P assembly clean package

@@ -99,7 +99,8 @@ should ideally execute each line in the code, code coverage should be 100%. To generate the JaCoCo report, run the Maven command:
- mvn test jacoco:restore-instrumented-classes jacoco:report@default-report. + mvn clean test jacoco:restore-instrumented-classes jacoco:report@default-report + .
Check the results of the report in target/site/jacoco/index.html in the project's root folder.