Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Drop "kotlinx" in package names of Lincheck classes and change the artifact location #185

Draft
wants to merge 1 commit into
base: develop
Choose a base branch
from
Draft
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
4 changes: 2 additions & 2 deletions CONTRIBUTING.md
Original file line number Diff line number Diff line change
Expand Up @@ -6,7 +6,7 @@ fixes/changes/improvements via pull requests.
## Submitting issues

Both bug reports and feature requests are welcome.
Submit issues [here](https://github.com/Kotlin/kotlinx-lincheck/issues).
Submit issues [here](https://github.com/JetBrains/lincheck/issues).

* Search for existing issues to avoid reporting duplicates.
* When submitting a bug report:
Expand All @@ -23,7 +23,7 @@ Submit issues [here](https://github.com/Kotlin/kotlinx-lincheck/issues).

## Submitting PRs

We love PRs. Submit PRs [here](https://github.com/Kotlin/kotlinx-lincheck/pulls).
We love PRs. Submit PRs [here](https://github.com/JetBrains/lincheck/pulls).
However, please keep in mind that maintainers will have to support the resulting code of the project,
so do familiarize yourself with the following guidelines.

Expand Down
21 changes: 16 additions & 5 deletions README.md
Original file line number Diff line number Diff line change
@@ -1,4 +1,4 @@
# kotlinx-lincheck
# Lincheck

[![Kotlin Beta](https://kotl.in/badges/beta.svg)](https://kotlinlang.org/docs/components-stability.html)
[![JetBrains official project](https://jb.gg/badges/official.svg)](https://confluence.jetbrains.com/display/ALL/JetBrains+on+GitHub)
Expand All @@ -13,6 +13,17 @@ generates a set of random concurrent scenarios,
examines them using either stress-testing or bounded model checking, and
verifies that the results of each invocation satisfy the required correctness property (linearizability by default).

## 📣 Package Renaming in Lincheck 2.18
Copy link

@whyoleg whyoleg May 12, 2023

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

minor comment from outside, as next version will be:

  • fully backward incompatible
  • new maven artifacts
  • new license

May be it's a good idea to call it lincheck 3.0? This will help users a lot during migration period :)

Copy link
Collaborator Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

That's a good point, thanks. The version "2.18" is more or less a placeholder for now, and the new release will likely be "3.0".

As we are also going to change the API dramatically, we are considering postponing this change and applying it only to the new API, keeping the current one in the "org.jetbrains.kotlinx.lincheck" package.

As Lincheck is not a Kotlin-specific framework, the repository has been recently moved from "Kotlin" GitHub organization to "JetBrains."
To complete the transition, we have also changed the package of Lincheck classes from `org.jetbrains.kotlinx.lincheck` to `org.jetbrains.lincheck`.

As a result, when upgrading Lincheck to version 2.18 or newer, you may encounter compile errors. However, resolving them is straightforward:

1. In your project, locate all usages of the package `org.jetbrains.kotlinx.lincheck`.
2. Replace all instances of `org.jetbrains.kotlinx.lincheck` with `org.jetbrains.lincheck`.

Following these steps will successfully fix any compilation errors arising from the package renaming in Lincheck.

## Documentation and Presentations

Please see the [official tutorial](/docs/topics/lincheck-guide.md) that showcases Lincheck features through examples.
Expand All @@ -32,7 +43,7 @@ repositories {

dependencies {
// Lincheck dependency
testImplementation("org.jetbrains.kotlinx:lincheck:2.17")
testImplementation("org.jetbrains.lincheck:lincheck:2.17")
}
```

Expand Down Expand Up @@ -66,9 +77,9 @@ tasks.withType<Test> {
The following Lincheck test easily finds a bug in the standard Java's `ConcurrentLinkedDeque`:

```kotlin
import org.jetbrains.kotlinx.lincheck.*
import org.jetbrains.kotlinx.lincheck.annotations.*
import org.jetbrains.kotlinx.lincheck.strategy.managed.modelchecking.*
import org.jetbrains.lincheck.*
import org.jetbrains.lincheck.annotations.*
import org.jetbrains.lincheck.strategy.managed.modelchecking.*
import org.junit.*
import java.util.concurrent.*

Expand Down
6 changes: 3 additions & 3 deletions RELEASE.md
Original file line number Diff line number Diff line change
@@ -1,5 +1,5 @@
# kotlinx-lincheck release checklist
Follow these steps to release a new `<version>` of `kotlinx-lincheck`.
# Lincheck release checklist
Follow these steps to release a new `<version>` of Lincheck.

1. Checkout `develop` branch: <br>
`git checkout develop`
Expand Down Expand Up @@ -37,7 +37,7 @@ Set `releaseVersion` property to `<version>` in the pop-up window. Make sure tha

11. In [Sonatype](https://oss.sonatype.org/) admin interface close staging repository and release it.

12. In [GitHub](https://github.com/Kotlin/kotlinx-lincheck/releases) interface:
12. In [GitHub](https://github.com/JetBrains/lincheck/releases) interface:
* Create a release named `lincheck-<version>`.
* Write a release notes message following the old ones as example of style.

Expand Down
2 changes: 1 addition & 1 deletion build.gradle.kts
Original file line number Diff line number Diff line change
Expand Up @@ -121,7 +121,7 @@ infra {
publishing {
include(":")

libraryRepoUrl = "https://github.com/Kotlin/kotlinx-lincheck"
libraryRepoUrl = "https://github.com/JetBrains/lincheck"
sonatype {}
}
}
Expand Down
2 changes: 1 addition & 1 deletion docs/cfg/buildprofiles.xml
Original file line number Diff line number Diff line change
Expand Up @@ -13,7 +13,7 @@
<buildprofiles>
<variables>
<enable-browser-edits>true</enable-browser-edits>
<browser-edits-url>https://github.com/Kotlin/kotlinx-lincheck/edit/master/docs/</browser-edits-url>
<browser-edits-url>https://github.com/JetBrains/lincheck/edit/master/docs/</browser-edits-url>
<allow-indexable-eaps>true</allow-indexable-eaps>
</variables>
<build-profile product="kl"/>
Expand Down
8 changes: 4 additions & 4 deletions docs/topics/constraints.md
Original file line number Diff line number Diff line change
Expand Up @@ -16,9 +16,9 @@ Here is the resulting test:

```kotlin
import org.jctools.queues.atomic.*
import org.jetbrains.kotlinx.lincheck.annotations.*
import org.jetbrains.kotlinx.lincheck.check
import org.jetbrains.kotlinx.lincheck.strategy.stress.*
import org.jetbrains.lincheck.annotations.*
import org.jetbrains.lincheck.check
import org.jetbrains.lincheck.strategy.stress.*
import org.junit.*

class MPSCQueueTest {
Expand Down Expand Up @@ -61,7 +61,7 @@ Execution scenario (post part):
Note that all consuming `poll()` and `peek()` invocations are performed from a single thread, thus satisfying the
"single-consumer" restriction.

> [Get the full code](https://github.com/Kotlin/kotlinx-lincheck/blob/guide/src/jvm/test/org/jetbrains/kotlinx/lincheck/test/guide/MPSCQueueTest.kt).
> [Get the full code](https://github.com/JetBrains/lincheck/blob/move-to-jb-organization/src/jvm/test/org/jetbrains/lincheck/test/guide/MPSCQueueTest.kt).
>
{type="note"}

Expand Down
28 changes: 14 additions & 14 deletions docs/topics/introduction.md
Original file line number Diff line number Diff line change
Expand Up @@ -38,7 +38,7 @@ When creating a project, use the Gradle build system.

dependencies {
// Lincheck dependency
testImplementation("org.jetbrains.kotlinx:lincheck:%lincheckVersion%")
testImplementation("org.jetbrains.lincheck:lincheck:%lincheckVersion%")
// This dependency allows you to work with kotlin.test and JUnit:
testImplementation("junit:junit:4.13")
}
Expand All @@ -54,7 +54,7 @@ When creating a project, use the Gradle build system.

dependencies {
// Lincheck dependency
testImplementation "org.jetbrains.kotlinx:lincheck:%lincheckVersion%"
testImplementation "org.jetbrains.lincheck:lincheck:%lincheckVersion%"
// This dependency allows you to work with kotlin.test and JUnit:
testImplementation "junit:junit:4.13"
}
Expand All @@ -67,9 +67,9 @@ When creating a project, use the Gradle build system.
1. In the `src/test/kotlin` directory, create a `BasicCounterTest.kt` file and add the following code:

```kotlin
import org.jetbrains.kotlinx.lincheck.annotations.*
import org.jetbrains.kotlinx.lincheck.*
import org.jetbrains.kotlinx.lincheck.strategy.stress.*
import org.jetbrains.lincheck.annotations.*
import org.jetbrains.lincheck.*
import org.jetbrains.lincheck.strategy.stress.*
import org.junit.*

class Counter {
Expand Down Expand Up @@ -121,10 +121,10 @@ which examines numerous executions with a bounded number of context switches.
The updated `BasicCounterTest` class will look like this:

```kotlin
import org.jetbrains.kotlinx.lincheck.annotations.*
import org.jetbrains.kotlinx.lincheck.check
import org.jetbrains.kotlinx.lincheck.strategy.managed.modelchecking.*
import org.jetbrains.kotlinx.lincheck.verifier.*
import org.jetbrains.lincheck.annotations.*
import org.jetbrains.lincheck.check
import org.jetbrains.lincheck.strategy.managed.modelchecking.*
import org.jetbrains.lincheck.verifier.*
import org.junit.*

class Counter {
Expand Down Expand Up @@ -176,7 +176,7 @@ The updated `BasicCounterTest` class will look like this:
* **T2**: The second thread resumes and increments the previously obtained counter value, incorrectly updating the
counter to `1`.

> [Get the full code](https://github.com/Kotlin/kotlinx-lincheck/blob/guide/src/jvm/test/org/jetbrains/kotlinx/lincheck/test/guide/BasicCounterTest.kt).
> [Get the full code](https://github.com/JetBrains/lincheck/blob/move-to-jb-organization/src/jvm/test/org/jetbrains/lincheck/test/guide/BasicCounterTest.kt).
>
{type="note"}

Expand All @@ -186,9 +186,9 @@ Let's now find a bug in the standard Java's `ConcurrentLinkedDeque` class.
The Lincheck test below finds a race between removing and adding an element to the head of the deque:

```kotlin
import org.jetbrains.kotlinx.lincheck.*
import org.jetbrains.kotlinx.lincheck.annotations.*
import org.jetbrains.kotlinx.lincheck.strategy.managed.modelchecking.*
import org.jetbrains.lincheck.*
import org.jetbrains.lincheck.annotations.*
import org.jetbrains.lincheck.strategy.managed.modelchecking.*
import org.junit.*
import java.util.concurrent.*

Expand Down Expand Up @@ -251,7 +251,7 @@ Parallel part trace:
| thread is finished | |
```

> [Get the full code](https://github.com/Kotlin/kotlinx-lincheck/blob/guide/src/jvm/test/org/jetbrains/kotlinx/lincheck/test/guide/ConcurrentLinkedDequeTest.kt).
> [Get the full code](https://github.com/JetBrains/lincheck/blob/move-to-jb-organization/src/jvm/test/org/jetbrains/lincheck/test/guide/ConcurrentLinkedDequeTest.kt).
>
{type="note"}

Expand Down
14 changes: 3 additions & 11 deletions docs/topics/lincheck-guide.md
Original file line number Diff line number Diff line change
Expand Up @@ -28,7 +28,7 @@ repositories {
}

dependencies {
testImplementation("org.jetbrains.kotlinx:lincheck:%lincheckVersion%")
testImplementation("org.jetbrains.lincheck:lincheck:%lincheckVersion%")
}
```

Expand All @@ -41,7 +41,7 @@ repositories {
}

dependencies {
testImplementation "org.jetbrains.kotlinx:lincheck:%lincheckVersion%"
testImplementation "org.jetbrains.lincheck:lincheck:%lincheckVersion%"
}
```

Expand All @@ -62,12 +62,4 @@ Lincheck features step-by-step:

## Additional references

* Workshop. Lincheck: Testing concurrency on the JVM: [Part 1](https://www.youtube.com/watch?v=YNtUK9GK4pA),
Hydra 2021, EN
* Workshop. Lincheck: Testing concurrency on the JVM: [Part 2](https://www.youtube.com/watch?v=EW7mkAOErWw),
Hydra 2021, EN
* [Lincheck. Testing concurrent data structures in Java](https://www.youtube.com/watch?v=YAb7YoEd6mM), Heisenbug 2019,
RU
* [Testing concurrent algorithms with Lincheck](https://www.youtube.com/watch?v=9cB36asOjPo), Joker 2019, RU
* [Lincheck: testing concurrent data structures on Java](https://www.youtube.com/watch?v=hwbpUEGHvvY), Hydra 2019, RU
* [Lock-free algorithms testing](https://www.youtube.com/watch?v=_0_HOnTSS0E), Joker 2017, RU
* "Lincheck: Testing concurrency on the JVM" workshop by Maria Sokolova: [Part 1](https://www.youtube.com/watch?v=YNtUK9GK4pA), [Part 2](https://www.youtube.com/watch?v=EW7mkAOErWw). Hydra 2021
10 changes: 5 additions & 5 deletions docs/topics/operation-arguments.md
Original file line number Diff line number Diff line change
Expand Up @@ -42,10 +42,10 @@ For this, configure the generator for a `key: Int` parameter:

```kotlin
import java.util.concurrent.*
import org.jetbrains.kotlinx.lincheck.annotations.*
import org.jetbrains.kotlinx.lincheck.check
import org.jetbrains.kotlinx.lincheck.paramgen.*
import org.jetbrains.kotlinx.lincheck.strategy.stress.*
import org.jetbrains.lincheck.annotations.*
import org.jetbrains.lincheck.check
import org.jetbrains.lincheck.paramgen.*
import org.jetbrains.lincheck.strategy.stress.*
import org.junit.*

class MultiMap<K, V> {
Expand Down Expand Up @@ -117,7 +117,7 @@ For this, configure the generator for a `key: Int` parameter:
Due to the small range of keys, Lincheck quickly reveals the race: when two values are being added concurrently by the same key,
one of the values may be overwritten and lost.

> [Get the full code](https://github.com/Kotlin/kotlinx-lincheck/blob/guide/src/jvm/test/org/jetbrains/kotlinx/lincheck/test/guide/MultiMapTest.kt).
> [Get the full code](https://github.com/JetBrains/lincheck/blob/move-to-jb-organization/src/jvm/test/org/jetbrains/lincheck/test/guide/MultiMapTest.kt).
>
{type="note"}

Expand Down
4 changes: 2 additions & 2 deletions docs/topics/progress-guarantees.md
Original file line number Diff line number Diff line change
Expand Up @@ -89,8 +89,8 @@ class ConcurrentSkipListMapTest {
At the moment, Lincheck supports only the obstruction-freedom progress guarantees. However, most real-life liveness bugs
add unexpected blocking code, so the obstruction-freedom check will also help with lock-free and wait-free algorithms.

> * Get the [full code of the example](https://github.com/Kotlin/kotlinx-lincheck/blob/guide/src/jvm/test/org/jetbrains/kotlinx/lincheck/test/guide/ConcurrentMapTest.kt).
> * See [another example](https://github.com/Kotlin/kotlinx-lincheck/blob/guide/src/jvm/test/org/jetbrains/kotlinx/lincheck/test/guide/ObstructionFreedomViolationTest.kt)
> * Get the [full code of the example](https://github.com/JetBrains/lincheck/blob/move-to-jb-organization/src/jvm/test/org/jetbrains/lincheck/test/guide/ConcurrentMapTest.kt).
> * See [another example](https://github.com/JetBrains/lincheck/blob/move-to-jb-organization/src/jvm/test/org/jetbrains/lincheck/test/guide/ObstructionFreedomViolationTest.kt)
> where the Michael-Scott queue implementation is tested for progress guarantees.
>
{type="note"}
Expand Down
12 changes: 6 additions & 6 deletions docs/topics/sequential-specification.md
Original file line number Diff line number Diff line change
Expand Up @@ -19,11 +19,11 @@ To provide a sequential specification of the algorithm for verification:
For example, here is the test to check correctness of `j.u.c.ConcurrentLinkedQueue` from the Java standard library.

```kotlin
import org.jetbrains.kotlinx.lincheck.*
import org.jetbrains.kotlinx.lincheck.annotations.*
import org.jetbrains.kotlinx.lincheck.annotations.Operation
import org.jetbrains.kotlinx.lincheck.strategy.stress.*
import org.jetbrains.kotlinx.lincheck.verifier.*
import org.jetbrains.lincheck.*
import org.jetbrains.lincheck.annotations.*
import annotations.org.jetbrains.lincheck.Operation
import org.jetbrains.lincheck.strategy.stress.*
import org.jetbrains.lincheck.verifier.*
import org.junit.*
import java.util.*
import java.util.concurrent.*
Expand Down Expand Up @@ -51,6 +51,6 @@ class SequentialQueue {
}
```

> Get the [full code of the examples](https://github.com/Kotlin/kotlinx-lincheck/blob/guide/src/jvm/test/org/jetbrains/kotlinx/lincheck/test/guide/ConcurrentLinkedQueueTest.kt).
> Get the [full code of the examples](https://github.com/JetBrains/lincheck/blob/move-to-jb-organization/src/jvm/test/org/jetbrains/lincheck/test/guide/ConcurrentLinkedQueueTest.kt).
>
{type="note"}
30 changes: 15 additions & 15 deletions docs/topics/testing-strategies.md
Original file line number Diff line number Diff line change
Expand Up @@ -28,9 +28,9 @@ Create a concurrent stress test for the `Counter`, following these steps:
The resulting code will look like this:

```kotlin
import org.jetbrains.kotlinx.lincheck.annotations.*
import org.jetbrains.kotlinx.lincheck.check
import org.jetbrains.kotlinx.lincheck.strategy.stress.*
import org.jetbrains.lincheck.annotations.*
import org.jetbrains.lincheck.check
import org.jetbrains.lincheck.strategy.stress.*
import org.junit.*

class Counter {
Expand Down Expand Up @@ -81,9 +81,9 @@ To change the stress testing strategy to model checking, replace `StressOptions(
test:

```kotlin
import org.jetbrains.kotlinx.lincheck.annotations.*
import org.jetbrains.kotlinx.lincheck.check
import org.jetbrains.kotlinx.lincheck.strategy.managed.modelchecking.*
import org.jetbrains.lincheck.annotations.*
import org.jetbrains.lincheck.check
import org.jetbrains.lincheck.strategy.managed.modelchecking.*
import org.junit.*

class Counter {
Expand Down Expand Up @@ -157,10 +157,10 @@ To configure the testing strategy, set options in the `<TestingMode>Options` cla
1. Set the options for scenario generation and execution for the `CounterTest`:

```kotlin
import org.jetbrains.kotlinx.lincheck.annotations.*
import org.jetbrains.kotlinx.lincheck.check
import org.jetbrains.kotlinx.lincheck.strategy.stress.*
import org.jetbrains.kotlinx.lincheck.verifier.*
import org.jetbrains.lincheck.annotations.*
import org.jetbrains.lincheck.check
import org.jetbrains.lincheck.strategy.stress.*
import org.jetbrains.lincheck.verifier.*
import org.junit.*

class Counter {
Expand Down Expand Up @@ -240,9 +240,9 @@ The method should be thread-safe, non-blocking, and never modify the data struct
states in the trace, add the `stateRepresentation()` function to the `CounterTest`:

```kotlin
import org.jetbrains.kotlinx.lincheck.annotations.*
import org.jetbrains.kotlinx.lincheck.check
import org.jetbrains.kotlinx.lincheck.strategy.managed.modelchecking.*
import org.jetbrains.lincheck.annotations.*
import org.jetbrains.lincheck.check
import org.jetbrains.lincheck.strategy.managed.modelchecking.*
import org.junit.Test

class Counter {
Expand Down Expand Up @@ -298,8 +298,8 @@ printed at the switch points that modify the counter state (they start with `STA
In case of stress testing, Lincheck prints the state representation right before and after the parallel part of the scenario,
as well as at the end.

> * Get the [full code of these examples](https://github.com/Kotlin/kotlinx-lincheck/blob/guide/src/jvm/test/org/jetbrains/kotlinx/lincheck/test/guide/CounterTest.kt)
> * See more [test examples](https://github.com/Kotlin/kotlinx-lincheck/blob/guide/src/jvm/test/org/jetbrains/kotlinx/lincheck/test/guide/StackTest.kt)
> * Get the [full code of these examples](https://github.com/JetBrains/lincheck/blob/move-to-jb-organization/src/jvm/test/org/jetbrains/lincheck/test/guide/CounterTest.kt)
> * See more [test examples](https://github.com/JetBrains/lincheck/blob/move-to-jb-organization/src/jvm/test/org/jetbrains/lincheck/test/guide/StackTest.kt)
>
{type="note"}

Expand Down
2 changes: 1 addition & 1 deletion gradle.properties
Original file line number Diff line number Diff line change
Expand Up @@ -8,7 +8,7 @@
# with this file, You can obtain one at http://mozilla.org/MPL/2.0/.
#

group=org.jetbrains.kotlinx
group=org.jetbrains.lincheck
name=lincheck
version=2.18-SNAPSHOT

Expand Down
Original file line number Diff line number Diff line change
Expand Up @@ -7,9 +7,9 @@
* Mozilla Public License, v. 2.0. If a copy of the MPL was not distributed
* with this file, You can obtain one at http://mozilla.org/MPL/2.0/.
*/
package org.jetbrains.kotlinx.lincheck
package org.jetbrains.lincheck

import org.jetbrains.kotlinx.lincheck.annotations.*
import org.jetbrains.lincheck.annotations.*
import java.lang.reflect.Method
import kotlin.reflect.jvm.*

Expand Down
Loading