diff --git a/contributing.md b/contributing.md index d5811b3..97a3f50 100644 --- a/contributing.md +++ b/contributing.md @@ -7,56 +7,70 @@ open-source project, and welcomes contributions in the form of feature code, bug reports and fixes, tests, feature suggestions and anything else which may help to make it better software. +Kaleidoscope is one of a large number of +[Soundness](https://github.com/propensive/soundness/) projects, which benefit +from having consistent integrations and automated admin tasks. These will be +developed across all projects simultaneously, and there's a roadmap for +improving them. So we are not currently looking for enhancements in this area, +but you're welcome to enquire. + ## Before Starting -It’s a good idea to [discuss](https://discord.gg/7b6mpF6Qcf) potential +It’s a good idea to [discuss](https://discord.gg/MBUrkTgMnA) potential changes with one of the maintainers before starting work. Although efforts are made to document future development work using the [issue tracker](/issues), it will not always be up-to-date, and the maintainers may have useful information to share on plans. -The worst-case scenario would be for a contributor to spend a large amount of -time producing a PR, only for it to be rejected by the maintainers because it -is not consistent with their plans. A quick conversation before starting work -can save a lot of time. +A bad scenario would be for a contributor to spend a lot of time producing a +pull request, only for it to be rejected by the maintainers for being +inconsistent with their plans. A quick conversation before starting work can +save a lot of time. If a response is not forthcoming in the [Discord -chatroom](https://discord.gg/7b6mpF6Qcf), contacting one of the project -maintainers directly _but publicly_ may help. Please __do not__ contact the -maintainers privately, as it misses a good opportunity to share knowledge with -a wide audience. Jon Pretty can usually be contacted [on -X](https://x.com/propensive). +chatroom](https://discord.gg/MBUrkTgMnA), open a [GitHub +issue](https://github.com/propensive/kaleidoscope/issues) or contact the project +maintainer directly _but publicly_. Please __do not__ contact the maintainer +about technical issues privately, as it misses a good opportunity to share +knowledge with a wider audience, unless there is a good reason to do so. Jon +Pretty can usually be contacted [on X](https://x.com/propensive). All development work—whether bugfixing or implementing new features—should have a corresponding issue before work starts. If you have commit rights to the `propensive/kaleidoscope` repository, push to a branch named -after the issue number, prefixed with `issue/`, for example, `issue/423`. +after the issue number, prefixed with `issue/`, for example, `issue/23`. ## Contribution standards Pull requests should try to follow the coding style of existing code in the repository. They are unlikely to be rejected on grounds of formatting, except in extreme cases. Kaleidoscope does not use automatic code-formatting because it -has proven to produce unreliable results (and furthermore, hand-formatting is -not particularly laborious). +has proven to produce unreliable and unsatisfactory results (and furthermore, +hand-formatting is not particularly laborious). Unfortunately an official coding style guide does not yet exist. -Any code that is inconsistently formatted will be fixed before merging, without -complaint. +Any code that is inconsistently formatted will be tidied up, if necessary, by +the project maintainers, though well-formatted code is appreciated. + +## Code reviews Pull requests should have at least one review before being merged. When opening -a PR, contributors are welcome to suggest a reviewer. Pull requests should be -left in _draft_ mode until they are believed to be ready for review. +a pull request, contributors are welcome to suggest a reviewer. Pull requests +should be left in _draft_ mode until they are believed to be ready for review. -For code contributions, we prefer pull requests with corresponding tests. But -we should not _let perfect be the enemy of the good_. Changes which break -existing tests, however, are likely to be rejected during review. +The preferred method of reviewing a pull request is to schedule a video call +with the reviewer and talk through it. It is much faster to share understanding +between the contributor and reviewer this way. + +For code contributions, we prefer pull requests with corresponding tests, if +that's appropriate. Changes which break existing tests, however, are likely to +be rejected during review. ## Reporting issues New issues are welcome, both as bug reports and feature suggestions. More -detail is preferable, and the clearest and most detailed reports will most +precision is preferable, and the clearest and most detailed reports will most likely be addressed sooner, but a short report from a busy developer is still preferred over a bug we never hear about. We will ask for more detail in triage if it’s needed. @@ -64,9 +78,11 @@ if it’s needed. ## Conduct Contributors and other participants in online discussions are expected to be -polite, on-topic and to nurture a pleasant development environment for all -Kaleidoscope’s users. Propensive OÜ reserves the right to censure -and—in extreme cases—ban users whose behavior, in their opinion, is -detrimental toward this goal. But individualism is valued, and nobody should -feel constrained in how they express themselves. +civil, on-topic and to nurture a pleasant development environment for all +Kaleidoscope’s users. Individualism is valued, and nobody should feel +constrained in how they express themselves, as long as they adhere to the +expectations. + +Propensive OÜ have some powers to address conduct issues, but that will +start with an informal conversation, and without prejudice. diff --git a/readme.md b/readme.md index 1dfc015..fae6e05 100644 --- a/readme.md +++ b/readme.md @@ -1,10 +1,10 @@ [GitHub Workflow](https://github.com/propensive/kaleidoscope/actions) -[](https://discord.gg/7b6mpF6Qcf) +[](https://discord.gg/MBUrkTgMnA) # Kaleidoscope -__Statically-checked inline matching on regular expressions__ +__Statically-checked inline pattern matching on regular expressions__ Kaleidoscope is a small library to make pattern matching against strings more pleasant. Regular expressions can be written directly in patterns, and @@ -30,17 +30,16 @@ structured objects. Kaleidoscope makes it easier to move away from strings. - simpler "glob" syntax is also provided -## Availability Plan +## Availability -Kaleidoscope has not yet been published. The medium-term plan is to build Kaleidoscope -with [Fury](https://github.com/propensive/fury) and to publish it as a source build on -[Vent](https://github.com/propensive/vent). This will enable ordinary users to write and build -software which depends on Kaleidoscope. +Kaleidoscope is available as a binary for Scala 3.4.0 and later, from [Maven +Central](https://central.sonatype.com). To include it in an `sbt` build, use +the coordinates: +```scala +libraryDependencies += "dev.soundness" % "kaleidoscope-core" % "0.1.0" +``` -Subsequently, Kaleidoscope will also be made available as a binary in the Maven -Central repository. This will enable users of other build tools to use it. -For the overeager, curious and impatient, see [building](#building). ## Getting Started