diff --git a/.github/workflows/gradle-build.yml b/.github/workflows/gradle-build.yml new file mode 100644 index 0000000..367c95b --- /dev/null +++ b/.github/workflows/gradle-build.yml @@ -0,0 +1,27 @@ +name: Gradle Build + +on: [push, pull_request] + +# Allow cancelling all previous runs for the same branch +# See https://docs.github.com/en/actions/using-workflows/workflow-syntax-for-github-actions#concurrency +concurrency: + group: ${{ github.workflow }}-${{ github.ref }} + cancel-in-progress: true + +jobs: + build: + runs-on: ubuntu-20.04 + + steps: + - uses: actions/checkout@v4 + - name: Set up JDK 11 + uses: actions/setup-java@v3 + with: + java-version: 11 + distribution: liberica + - name: Gradle Wrapper Validation + uses: gradle/wrapper-validation-action@v1.0.4 + - uses: gradle/gradle-build-action@v2 + with: + arguments: build --stacktrace -x test + diff --git a/.github/workflows/gradle-test.yml b/.github/workflows/gradle-test.yml new file mode 100644 index 0000000..c589f6f --- /dev/null +++ b/.github/workflows/gradle-test.yml @@ -0,0 +1,26 @@ +name: Gradle Test + +on: [push, pull_request] + +# Allow cancelling all previous runs for the same branch +# See https://docs.github.com/en/actions/using-workflows/workflow-syntax-for-github-actions#concurrency +concurrency: + group: ${{ github.workflow }}-${{ github.ref }} + cancel-in-progress: true + +jobs: + build: + runs-on: ubuntu-20.04 + + steps: + - uses: actions/checkout@v4 + - name: Set up JDK 11 + uses: actions/setup-java@v3 + with: + java-version: 11 + distribution: liberica + - name: Gradle Wrapper Validation + uses: gradle/wrapper-validation-action@v1.0.4 + - uses: gradle/gradle-build-action@v2 + with: + arguments: test diff --git a/README.md b/README.md index f1f960b..6058aec 100644 --- a/README.md +++ b/README.md @@ -1,252 +1,103 @@ -# JetBrains Academy Java Course Template - [![official project](https://jb.gg/badges/official.svg)](https://confluence.jetbrains.com/display/ALL/JetBrains+on+GitHub) -[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT) - -> **Note** -> -> Click the Use this template button and clone it in IntelliJ IDEA. - -**JetBrains Academy Java course template** is a repository that provides a -pure template to make it easier to create a new Java course with the [JetBrains Academy -plugin][ref:plugin.marketplace] (check out the [Creating a repository from a template][gh:template] article). +[![Gradle Build](https://github.com/jetbrains-academy/refactoring-java-course/actions/workflows/gradle-build.yml/badge.svg)](https://github.com/jetbrains-academy/refactoring-java-course/actions/workflows/gradle-build.yml) -The main goal of this template is to speed up the setup phase -of Java course development for both new and experienced educators -by preconfiguring the project scaffold and CI, -linking to the proper documentation pages, and keeping everything organized. +# Introduction to IDE Code Refactoring in Java -If you're still not quite sure what this is all about, read our introduction: [What is the JetBrains Academy plugin?][docs:intro] +This course will introduce you to refactorings and the IDE features that will help you to perform them in an effective way. +You will learn to recognize refactoring opportunities in code and to deal with them. +Using automatic IDE refactorings, you will transform code to improve its structure, readability, and maintainability. -> **Note** -> -> Click the Watch button on the top to be notified about releases containing new features and fixes. +The course consists of 8 sections. Each section focuses on one group of refactorings and +provides brief theory and several small tasks for practice. +We will move on from small local refactoring changes to more complex ones, which affect the entire project architecture. -### Table of contents +Topics covered: -In this README, we will highlight the following elements of template-project creation: +- refactoring definition; +- code quality and code smells; +- kinds of refactoring techniques; +- IDE refactoring features; +- code style and formatting; +- code style schema and EditorConfig; +- automatic formatting using IDE; +- naming rules; +- rename refactoring; +- move refactoring; +- pull up and push down refactoring; +- extract refactoring; +- inline refactoring; +- design patterns and their relationships with refactoring. -- [Getting started](#getting-started) -- [Gradle configuration](#gradle-configuration) -- [Course info configuration file](#course-info-configuration-file) -- [Course ignore file](#course-ignore-file) -- [Sample code](#sample-code) -- [Testing](#testing) -- [Predefined Run/Debug configurations](#predefined-rundebug-configurations) -- [Continuous integration](#continuous-integration) -- [Useful links](#useful-links) - -## Getting started -Before we dive into course development and everything related to it, it's worth mentioning the benefits of using GitHub Templates. -By creating a new project with the current template, you start with no history or reference to this repository. -This allows you to create a new repository easily, without copying and pasting previous content, cloning repositories, or clearing the history manually. +## Technical requirements -All you need to do is click the Use this template button (you must be logged in with your GitHub account). +Before starting this course, check the following requirements. -![Use this template][file:use-template-blur] +1. Your computer needs to have a stable internet connection. +2. Git version control system needs to be installed on your computer (link to the git site: https://git-scm.com/). +3. Make sure that the path to the root folder of the course does not contain spaces, special characters, or non-Latin characters. +4. Make sure that you use the [IntelliJ IDEA](https://www.jetbrains.com/idea/download/?_ga=2.189310830.494255415.1682514714-1823138827.1669894241&_gac=1.83806948.1682684894.Cj0KCQjw3a2iBhCFARIsAD4jQB3QkDU43KtbIx2HzEz02KvcN7Ma3QGzkIbyX4KS3H4x8b2bl9p4EfYaAvWsEALw_wcB&_gl=1*1h13lr8*_ga*MTgyMzEzODgyNy4xNjY5ODk0MjQx*_ga_9J976DJZ68*MTY4MjY5NDIyMy4xMjUuMS4xNjgyNjk0MjM4LjQ1LjAuMA..#section=windows) with version at least `2023.1.1`. +5. Make sure that you use the [JetBrains Academy](https://plugins.jetbrains.com/plugin/10081-jetbrains-academy) plugin with version at least `2023.1`. -The most convenient way of getting your new project from GitHub is the Get from VCS action available on the Welcome Screen, -where you can filter your GitHub repository by its name. - -![Use this template][file:use-this-template.png] +The course is integrated into the [IntelliJ IDEA IDE](https://www.jetbrains.com/idea/), which has a free Community license. +You can use this license to complete the course. +If you have some troubles with the course installation, feel free to contact us by email at education@jetbrains.com. +## Getting started -As the last step, you need to manually review the configuration variables described in the [`gradle.properties`][file:gradle.properties] file and *optionally* move sources from the *org.jetbrains.academy.java.template* package to the one that works best for you. -Then you can get to work and implement your ideas. +This course is [available](https://plugins.jetbrains.com/plugin/23048-introduction-to-ide-code-refactoring) on JetBrains +Marketplace and can be installed from the IntelliJ IDEA IDE directly, but you can also use it in the Course Creator mode +or create a course archive from the source code. -## Gradle configuration +### Getting started: create a course preview from the source code -The recommended method for Java course development involves using the [Gradle][gradle] setup. +You can create a [course preview](https://plugins.jetbrains.com/plugin/10081-jetbrains-academy/docs/educator-start-guide.html#preview_course) from the source code: +1. Clone the repository: + ```text + git clone https://github.com/jetbrains-academy/refactoring-java-course.git + ``` -A course built using the JetBrains Academy Java course template includes a Gradle configuration already set up. -This gradle file sets up all base dependencies and plugins for the course. -For each gradle module (each task in the course and extra modules like `common` as well) -it includes [JUnit5][ref:junit5] tests. -It also marks the `source` and `test` folders as source- and test- source sets in the project. +2. Build the project: + ```text + ./gradlew build + ``` -### Gradle properties +3. Install the [JetBrains Academy](https://plugins.jetbrains.com/plugin/10081-jetbrains-academy/docs/install-jetbrains-academy-plugin.html) plugin from JetBrains Marketplace. -The project-specific configuration file [`gradle.properties`][file:gradle.properties] contains: +4. Create a new [course preview](https://plugins.jetbrains.com/plugin/10081-jetbrains-academy/docs/educator-start-guide.html#preview_course). -| Property name | Description | -|---------------------|---------------------------------------------------------------| -| `courseGroup` | Package name. | -| `courseVersion` | The current version of the course in [SemVer][semver] format. | -| `gradleVersion` | Version of Gradle used for course development. | -| `jvmVersion` | Version of the JVM used for course development. | +### Getting started: create a course archive -## Course template structure +You can create a [course archive](https://plugins.jetbrains.com/plugin/10081-jetbrains-academy/docs/educator-start-guide.html#fe7010f2) from the source code: +1. Clone the repository: + ```text + git clone https://github.com/jetbrains-academy/refactoring-java-course.git + ``` -A generated JetBrains Academy Java Course Template repository contains the following content structure: +2. Build the project: + ```text + ./gradlew build + ``` -``` -. -├── .github/ GitHub Actions workflows -├── .run/ Predefined Run/Debug Configurations -├── build/ Output build directory -├── gradle -│ └── wrapper/ Gradle Wrapper -├── common Course sources common for all sections -│ └── src -│ └── main -│ ├── java/ Java production sources -│ └── resources/ Resources - images, icons -├── courseSection/ An example of the course section -│ ├── courseLesson/ An example of the course lesson -│ │ ├── theoryTask/ An example of a theory task -│ │ │ ├── src/ Task sources -│ │ │ │ └── ... -│ │ │ ├── task.md Task/theory description -│ │ │ └── task-info.yaml Task config file -│ │ ├── quizTask/ An example of a quiz task -│ │ │ ├── src/ Task sources -│ │ │ │ └── ... -│ │ │ ├── task.md Task/quiz description -│ │ │ └── task-info.yaml Task config file -│ │ ├── programmingTask/ An example of a programming task -│ │ │ ├── src/ Task sources -│ │ │ │ └── ... -│ │ │ ├── test/ Task tests -│ │ │ │ └── ... -│ │ │ ├── task.md Task description -│ │ │ └── task-info.yaml Task config file -│ │ └── lesson-info.yaml Lesson config file -│ ├── courseFrameworkLesson/ An example of the course framework lesson -│ │ ├── ... Several examples of lessons -│ │ └── lesson-info.yaml Lesson config file -│ └── section-info.yaml Section config file -├── .courseignore Course ignoring rules -├── .gitignore Git ignoring rules -├── build.gradle.kts Gradle configuration -├── course-info.yaml Course info configuration file -├── gradle.properties Gradle configuration properties -├── gradlew *nix Gradle Wrapper script -├── gradlew.bat Windows Gradle Wrapper script -├── LICENSE License, MIT by default -├── README.md README -└── settings.gradle.kts Gradle project settings -``` +3. Install the [JetBrains Academy](https://plugins.jetbrains.com/plugin/10081-jetbrains-academy/docs/install-jetbrains-academy-plugin.html) plugin from JetBrains Marketplace. -## Course info configuration file - -The course info configuration file is the [course-info.yaml][file:course-info.yaml] file located in the root directory. -It provides general information about the course, like description, language, etc. - -```yaml -type: marketplace -title: JetBrains Academy Java course template -language: English -summary: Course description -programming_language: Java -content: - - courseSection -environment_settings: - jvm_language_level: JDK_17 -``` +4. Create a new [course archive](https://plugins.jetbrains.com/plugin/10081-jetbrains-academy/docs/educator-start-guide.html#fe7010f2). -## Course ignore file +## Run tests -The course ignore file is the [.courseignore][file:courseignore] file located in the root directory. -It provides the list of files or directories that will be ignored in the final course preview or archive. +To run tests locally, you just need to build the project and run the following command: ```text -README.md -/.run +./gradlew test ``` -You can find more information about the course preview in the [Course preview][ref:course.preview] section. Information -about creating a course archive and uploading it to the marketplace is in the [Course distribution][ref:course.distribution] section. - -## Sample code - -The prepared template provides an example of a course with one section, two lessons, and five tasks in total. - -![Course structure in the course creator mode][file:course-structure-author] - -Each course may have an unlimited number of sections, lessons, and tasks. -Students will see almost the same course structure as the educator (course author): - -![Course structure in the course student mode][file:course-structure-student] - -The main difference is in framework lessons, which display -only task files, without intermediate steps. - -You can read more about framework lessons in the official documentation in the [Framework Lessons Creation][ref:framework.lessons.creation] section. - -> **Note** -> -> Click Course Creator -> Create Course Preview in the context menu in the root of the repository to create a course preview. - - -The JetBrains Academy plugin provides five different types of tasks, -and you can combine them inside one lesson (whether regular or framework). -You can read more about tasks in the official documentation in the [Task][ref:tasks] section. - -## Testing - -To check the programming exercises for [**edu**][ref:tasks] tasks, you need to write tests. -It contains functionality to test student solutions by using the [Java Reflection API][ref:java.reflection.api] under the hood. -This approach allows you to call students' functions that do not exist yet. -It is a powerful mechanism that enables you to create excesses without predefined classes or function -templates and check their signature and behaviour properly. - -You can find little examples of programming tasks in the repository in the `Tests.java` files: -in [course lesson][file:course.lesson.tests] and [course framework lesson][file:course.framework.lesson.tests]. - -## Predefined Run/Debug configurations - -Within the default project structure, there is a `.run` directory provided, which contains predefined *Run/Debug configurations* that expose corresponding Gradle tasks: - -![Run/Debug configurations][file:run-debug-configurations] - -| Configuration name | Description | -|--------------------------|--------------------------------------------------------------------------------| -| Build course | Runs `:build` Gradle task with tests only. | - -## Continuous integration - -Continuous integration depends on [GitHub Actions][gh:actions], a set of workflows that make it possible to automate your testing and release process. -Thanks to such automation, you can delegate the testing and verification phases to the Continuous Integration (CI) and instead focus on development (and writing more tests). - -In the `.github/workflows` directory, you can find definitions for the following GitHub Actions workflows: -- [Build](.github/workflows/gradle-build.yml) - - Builds your course - - Runs all tests for all tasks - -## Useful links - -- [JetBrains Academy plugin][ref:plugin.marketplace] -- [Course creator start guide][ref:course.creator.start.guide] -- [Courses on Marketplace][ref:marketplace] - -[gh:actions]: https://help.github.com/en/actions -[gh:template]: https://docs.github.com/en/repositories/creating-and-managing-repositories/creating-a-repository-from-a-template - -[ref:marketplace]: https://plugins.jetbrains.com/education -[ref:course.creator.start.guide]: https://plugins.jetbrains.com/plugin/10081-jetbrains-academy/docs/educator-start-guide.html -[ref:plugin.marketplace]: https://plugins.jetbrains.com/plugin/10081-jetbrains-academy -[ref:course.preview]: https://plugins.jetbrains.com/plugin/10081-jetbrains-academy/docs/educator-start-guide.html#preview_course -[ref:course.distribution]: https://plugins.jetbrains.com/plugin/10081-jetbrains-academy/docs/educator-start-guide.html#course_distribution -[ref:framework.lessons.creation]: https://plugins.jetbrains.com/plugin/10081-jetbrains-academy/docs/framework-lessons-guide-for-course-creators.html#a81e8983 -[ref:tasks]: https://plugins.jetbrains.com/plugin/10081-jetbrains-academy/docs/framework-lessons-guide-for-course-creators.html#a81e8983 -[ref:java.reflection.api]: https://docs.oracle.com/javase/8/docs/technotes/guides/reflection/index.html -[ref:junit5]: https://junit.org/junit5/ - -[docs:intro]: https://plugins.jetbrains.com/plugin/10081-jetbrains-academy/docs/jetbrains-academy-plugin-faq.html#what_is_the_jetbrains_academy_plugin +The tests use the Java Reflection API under the hood to check the user's tasks. -[file:gradle.properties]: ./gradle.properties -[file:course-info.yaml]: ./course-info.yaml -[file:courseignore]: .courseignore -[file:course.lesson.tests]: ./courseSection/courseLesson/programmingTask/test/Tests.java -[file:course.framework.lesson.tests]: ./courseSection/courseFrameworkLesson/programmingTask/test/Tests.java +## Want to know more? -[gradle]: https://gradle.org +If you have questions about the course or the tasks or if you find some errors, +you can ask questions and participate in discussions in repository [issues](https://github.com/jetbrains-academy/refactoring-java-course/issues). -[semver]: https://semver.org +## Contribution -[file:use-this-template.png]: common/src/main/resources/images/get-from-version-control.png -[file:course-structure-author]: common/src/main/resources/images/course-structure-author.png -[file:course-structure-student]: common/src/main/resources/images/course-structure-student.png -[file:run-debug-configurations]: common/src/main/resources/images/run-debug-configurations.png -[file:use-template-blur]: common/src/main/resources/images/use_template_blur.jpg +Please be sure to review the [project's contributing guidelines](./contributing.md) to learn how to help the project. diff --git a/contributing.md b/contributing.md new file mode 100644 index 0000000..62849cf --- /dev/null +++ b/contributing.md @@ -0,0 +1,46 @@ +# What this repository is + +This repository contains sources of the _Introduction to IDE Code Refactoring in Java_ course. + +# Contributing + +We love contributions! +We are happy to see fixes of the existing bugs and tasks and tests mistakes. +The current tasks can be found in the [open issues](https://github.com/jetbrains-academy/refactoring-java-course/issues) in the project. +If you have some questions or find bugs or mistakes, please do not hesitate to open new ones. + +Please, add a comment to the issue, if you're starting work on it. + +If you add some common functionality, e.g. for the test system, it is important to add comments to describe new behaviour. +This will help other developers and users to use them correctly. + +## Submitting patches + +The best way to submit a patch is to [fork the project on GitHub](https://help.github.com/articles/fork-a-repo/) +and then send us a [pull request](https://help.github.com/articles/creating-a-pull-request/) +to the `main` branch via [GitHub](https://github.com). + +If you create your own fork, it might help to enable rebase by default +when you pull by executing +``` bash +git config --global pull.rebase true +``` +This will avoid your local repo having too many merge commits +which will help keep your pull request simple and easy to apply. + +## Search and fix formatting issues + +We use the Detekt tool as the main static analysis tool. +To build the projects with Detekt you need to run the build task with `-PrunDetekt` property. + +## Checklist + +Before submitting the pull request, make sure that you can say "YES" to each point in this short checklist: + +- You provided the link to the related issue(s) from the repository; +- You made a reasonable amount of changes related only to the provided issues; +- You can explain changes made in the pull request; +- You ran the build locally and verified new functionality/fixed bugs; +- You ran related tests locally (or add new ones) and they passed; +- You don't have code-style problems according the [GitHub Actions](https://github.com/jetbrains-academy/refactoring-java-course/tree/main/.github/workflows) +- You do not have merge conflicts in the pull request.