From e97748dc42b0031cc45b65cf63d98b0a34fba6fe Mon Sep 17 00:00:00 2001 From: propensive Date: Fri, 19 Jul 2024 20:51:29 +0000 Subject: [PATCH] Apply automatic changes --- contributing.md | 68 ++++++++++++++++++++++++++++++------------------- doc/lines.md | 1 + readme.md | 14 +++------- 3 files changed, 46 insertions(+), 37 deletions(-) create mode 100644 doc/lines.md diff --git a/contributing.md b/contributing.md index 0be1013..379d467 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. +Larceny 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/larceny/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/larceny` 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. Larceny 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 -Larceny’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 +Larceny’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/doc/lines.md b/doc/lines.md new file mode 100644 index 0000000..99ca0d5 --- /dev/null +++ b/doc/lines.md @@ -0,0 +1 @@ +346 diff --git a/readme.md b/readme.md index 94949bc..f335ea5 100644 --- a/readme.md +++ b/readme.md @@ -1,5 +1,5 @@ [GitHub Workflow](https://github.com/propensive/larceny/actions) -[](https://discord.gg/7b6mpF6Qcf) +[](https://discord.com/invite/MBUrkTgMnA) # Larceny @@ -10,7 +10,7 @@ Unlike runtime errors, compilation errors prevent successful compilation, which makes them harder to test, since we can't even compile the units tests we want to write and run to test them! -_Larceny_ makes it possible to write those tests. Code which would normally +__Larceny__ makes it possible to write those tests. Code which would normally fail compilation, for any reason (provided it parses as well-formed Scala) is permitted inside certain blocks of code, but instead of being compiled and run, instead returns a list of compilation errors, as runtime values, which are @@ -24,17 +24,9 @@ perfect for testing. - unit tests on compilation errors can be written in the most natural way -## Availability Plan +## Availability -Larceny has not yet been published. The medium-term plan is to build Larceny -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 Larceny. -Subsequently, Larceny 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