~jan0sch/smederee

Showing details for patch 24fd74a0aa69d0ef52f9c8466e0f68aa3961c691.
2022-11-06 (Sun), 5:23 PM - Jens Grassel - 24fd74a0aa69d0ef52f9c8466e0f68aa3961c691

Overhaul and adjust contribution guide.

- add coding style guide
- adjust contribution guide based upon C4.2
- still incomplete
Summary of changes
1 files added
  • CODINGSTYLE.md
1 files modified with 124 lines added and 28 lines removed
  • CONTRIBUTING.md with 124 added and 28 removed lines
diff -rN -u old-smederee/CODINGSTYLE.md new-smederee/CODINGSTYLE.md
--- old-smederee/CODINGSTYLE.md	1970-01-01 00:00:00.000000000 +0000
+++ new-smederee/CODINGSTYLE.md	2025-02-01 15:41:56.817444789 +0000
@@ -0,0 +1,47 @@
+# Coding Style Guidelines
+
+This document tries to describe the coding style to make it easier for everyone to contribute.
+
+## 1. Language
+
+The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", "SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY", and "OPTIONAL" in this document are to be interpreted as described in [RFC 2119](http://tools.ietf.org/html/rfc2119).
+
+## 2. General style and tooling
+
+1. The [Scalafmt](https://scalameta.org/scalafmt/) tool MUST be used to format the code.
+2. The configuration file for Scalafmt SHALL be the file [.scalafmt.conf](.scalafmt.conf) in the project root.
+3. The configuration SHALL be based upon the preset `defaultWithAlign` using the runner dialect `scala3` of Scalafmt with some additions.
+4. In the rare case of formatting interfering with code functionality, it is RECOMMENDED to disable automatic code formatting for the affected parts of the code only.
+
+### 2.1. Additions to the `defaultWithAlign` preset
+
+1. No unicode characters or literals are allowed in the source code e.g. `⇒` SHALL be written as `=>` or `←` as `<-` and so on.
+2. Rewrite rules SHOULD exist in the configuration to rewrite common unicode characters to their ASCII counterparts.
+3. The maximum line length in the source code SHOULD not be longer than 120 characters. There MAY be rare cases where exceptions are allowed.
+4. Imports SHOULD be written after the following guidelines:
+  1. Imports from Java core (e.g. `import java.time._`) MUST be written (grouped) first, followed by a blank line.
+  2. Multiple imports from the same package in curly braces SHALL have a space after the opening and before the closing brace (enforced by `spaces.inImportCurlyBraces=true`).
+  3. Imports SHALL be sorted by their ASCII names. This SHOULD be enforced by the `rewrite.imports.sort = ascii` setting of Scalafmt.
+5. Redundant braces SHALL be removed (enforced by `rewrite.rules` including `RedundantBraces`).
+6. Redundant parentheses SHALL be removed (enforced by `rewrite.rules` including `RedundantParens`).
+7. Configuration files for sbt (e.g. `*.sbt`) MUST NOT be formatted via Scalafmt.
+
+TODO: Describe `danglingParentheses.preset = true`
+
+## 3 Build configuration file style (sbt)
+
+1. Build definition and settings SHOULD be formatted to have one setting per line if possible.
+2. Dependencies SHALL be defined in the `lazy val library` block inside the `build.sbt` file, following these rules:
+  1. The version number SHALL be defined as a string in the `object Version` having a name clearly identifying the dependency e.g. `val cats = "2.8.0"`.
+  2. The dependencies SHALL be defined as values having meaningful names and they should be vertically aligned like in the following example:
+    ```scala
+    val catsCore   = "org.typelevel" %% "cats-core"   % Version.cats
+    val catsEffect = "org.typelevel" %% "cats-effect" % Version.catsEffect
+    ```
+3. Plugins for sbt SHALL be defined inside the `project/plugins.sbt` file and be vertically aligned like in the following example:
+```scala
+addSbtPlugin("io.spray"      % "sbt-revolver" % "0.9.1")
+addSbtPlugin("ch.epfl.scala" % "sbt-scalafix" % "0.10.4")
+addSbtPlugin("org.scalameta" % "sbt-scalafmt" % "2.4.6")
+```
+
diff -rN -u old-smederee/CONTRIBUTING.md new-smederee/CONTRIBUTING.md
--- old-smederee/CONTRIBUTING.md	2025-02-01 15:41:56.817444789 +0000
+++ new-smederee/CONTRIBUTING.md	2025-02-01 15:41:56.817444789 +0000
@@ -1,31 +1,127 @@
 # Contribution guide
 
-This project has adopted the [Collective Code Construction Contract
-(C4.2)](https://rfc.zeromq.org/spec:42) for contributing. Please read it
-before sending patches.
-
-Everyone is expected to follow the
-[Scala Code of Conduct](https://www.scala-lang.org/conduct/) when
-discussing the project on the available communication channels.
-If you are being harassed, please contact us immediately so that we can
-support you.
-
-## Additions to C4.2
-
-1. This project uses the AGPL 3.0 or later (see [LICENSE](LICENSE)).
-2. The project SHALL use the `darcs` distributed revision control system.
-3. Contributors are listed in the file [AUTHORS.md](AUTHORS.md). Add yourself if you have contributed.
-4. Please maintain the existing code style and try to keep your commits small and focused. The `scalafmt` tool SHALL be used to format the code according to the code style definition in the `.scalafmt.conf` file.
-5. Changes are documented in the file [CHANGELOG.md](CHANGELOG.md). Please use the section `Unreleased` to note your changes.
-
-## Release guide
-
-The changes in the section `Unreleased` in the [CHANGELOG.md](CHANGELOG.md)
-file MUST be moved to a section named after the release and a new empty
-`Unreleased` section MUST be created.
-
-A release SHALL be accompanied by an annotated tag
-(`darcs tag --edit-long-comment NAME`) that holds a description of the changes
-that are included in the release. This description SHOULD be same as in the file
-[CHANGELOG.md](CHANGELOG.md).
+Please read this guide if you want to contribute to the project.
+
+## 1. Code of Conduct
+
+Everyone is expected to follow the [Scala Code of Conduct](https://www.scala-lang.org/conduct/) when discussing the project on the available communication channels. If you are being harassed, please contact us immediately so that we can support you.
+
+## 2. Language
+
+The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", "SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY", and "OPTIONAL" in this document are to be interpreted as described in [RFC 2119](http://tools.ietf.org/html/rfc2119).
+
+## 3. Design
+
+### 3.1 Preliminaries
+
+1. The project SHALL use the darcs distributed revision control system.
+2. The project SHALL be hosted on [Smederee](https://smeder.ee), herein called the "Platform".
+3. The project SHALL use the Platform issue tracker.
+4. The project SHOULD have clearly documented guidelines for code style. The code style is documented in the file [CODINGSTYLE.md](CODINGSTYLE.md) in the project root.
+5. A "Contributor" is a person who wishes to provide a patch, being a set of commits that solve some clearly identified problem.
+6. A "Maintainer" is a person who merges patches to the project. Maintainers are not developers; their job is to enforce process.
+7. Contributors SHALL NOT have commit access to the repository unless they are also Maintainers.
+8. Maintainers SHALL have commit access to the repository.
+9. Everyone, without distinction or discrimination, SHALL have an equal right to become a Contributor under the terms of this contract.
+
+### 3.2 Licensing and Ownership
+
+1. The project SHALL use the AGPL 3.0 or later (see [LICENSE](LICENSE)).
+2. All contributions to the project source code ("patches") SHALL use the same license as the project.
+3. All patches are owned by their authors. There SHALL NOT be any copyright assignment process. Each Contributor SHALL be responsible for identifying themselves in the project Contributor list which is located in the file [AUTHORS.md](AUTHORS.md) in the project root.
+
+### 3.3 Patch Requirements
+
+1. Maintainers and Contributors MUST have a Platform account and SHOULD use their real names or a well-known alias.
+2. A patch SHOULD be a minimal and accurate answer to exactly one identified and agreed problem.
+3. A patch MUST adhere to the code style guidelines of the project if these are defined.
+4. A patch MUST adhere to the "Evolution of Public Contracts" guidelines defined below.
+5. A patch SHALL NOT include non-trivial code from other projects unless the Contributor is the original author of that code.
+6. A patch MUST compile cleanly and pass project self-tests on at least the principal target platform.
+7. A patch commit message MUST consist of a single short (less than 70 characters) line stating the problem being solved, followed by a blank line and then the proposed solution and summary of changes. If the patch addresses an issue from the issue tracker then the title line should instead contain the issue number and title (e.g. "ISSUE-NUMBER Issue summary").
+8. A "Correct Patch" is one that satisfies the above requirements.
+
+### 3.4 Development Process
+
+1. Change on the project SHALL be governed by the pattern of accurately identifying problems and applying minimal, accurate solutions to these problems.
+2. To request changes, a user SHOULD log an issue on the project Platform issue tracker.
+3. The user or Contributor SHOULD write the issue by describing the problem they face or observe.
+4. The user or Contributor SHOULD seek consensus on the accuracy of their observation, and the value of solving the problem.
+5. Users SHALL NOT log feature requests, ideas, suggestions, or any solutions to problems that are not explicitly documented and provable.
+6. Thus, the release history of the project SHALL be a list of meaningful issues logged and solved.
+7. To work on an issue, a Contributor SHALL fork the project repository and then work on their forked repository.
+8. TODO: To submit a patch, a Contributor SHALL create a Platform pull request back to the project. ???
+9. A Contributor SHALL NOT commit changes directly to the project.
+10. TODO: If the Platform implements pull requests as issues, a Contributor MAY directly send a pull request without logging a separate issue. ???
+11. TODO: To discuss a patch, people MAY comment on the Platform pull request, on the commit, or elsewhere. ???
+12. To accept or reject a patch, a Maintainer SHALL use the Platform interface.
+13. Maintainers SHOULD NOT merge their own patches except in exceptional cases, such as non-responsiveness from other Maintainers for an extended period (more than 1-2 days).
+14. Maintainers SHALL NOT make value judgments on correct patches.
+15. Maintainers SHALL merge correct patches from other Contributors rapidly.
+16. Maintainers MAY merge incorrect patches from other Contributors with the goals of (a) ending fruitless discussions, (b) capturing toxic patches in the historical record, (c) engaging with the Contributor on improving their patch quality.
+17. The user who created an issue SHOULD close the issue after checking the patch is successful.
+18. Any Contributor who has value judgments on a patch SHOULD express these via their own patches.
+19. Maintainers SHOULD close user issues that are left open without action for an uncomfortable period of time.
+
+### 3.5 Branches and Releases
+
+1. The project SHALL have one main branch that always holds the latest in-progress version and SHOULD always build.
+2. The project SHALL NOT use topic branches for any reason. Personal forks MAY use topic branches.
+3. To make a stable release a Maintainer shall tag the repository. Stable releases SHALL always be released from the main branch.
+
+#### 3.5.1 Release guide
+
+The changes in the section `Unreleased` in the [CHANGELOG.md](CHANGELOG.md) file MUST be moved to a section named after the release and a new empty `Unreleased` section MUST be created.
+
+The release `NAME` shall follow the specification described in the CHANGELOG file e.g. `major`.`minor`.`patchlevel` prefixed with a lower case `v`, for example: `v1.0.3`.
+
+A release SHALL be accompanied by an annotated tag (`darcs tag --edit-long-comment NAME`) that holds a description of the changes that are included in the release. This description SHOULD be same as in the file [CHANGELOG.md](CHANGELOG.md).
+
+Please note that lines starting with `#` are ignored by darcs therefore the sections like `Added`, `Fixed` etc. SHALL be written in the alternate heading syntax of markdown. Example:
+
+```
+v0.2.0
+
+Added
+-----
+
+- a
+- b
+
+Fixed
+-----
+
+- c
+- d
+
+```
+
+### 3.6 Evolution of Public Contracts
+
+1. All Public Contracts (APIs or protocols) SHALL be documented.
+2. All Public Contracts SHOULD have space for extensibility and experimentation.
+3. A patch that modifies a stable Public Contract SHOULD not break existing applications unless there is overriding consensus on the value of doing this.
+4. A patch that introduces new features SHOULD do so using new names (a new contract).
+5. New contracts SHOULD be marked as "draft" until they are stable and used by real users.
+6. Old contracts SHOULD be deprecated in a systematic fashion by marking them as "deprecated" and replacing them with new contracts as needed.
+7. When sufficient time has passed, old deprecated contracts SHOULD be removed.
+8. Old names SHALL NOT be reused by new contracts.
+
+### 3.7 Project Administration
+
+1. The project founders SHALL act as Administrators to manage the set of project Maintainers.
+2. The Administrators SHALL ensure their own succession over time by promoting the most effective Maintainers.
+3. A new Contributor who makes correct patches, who clearly understands the project goals, and the process SHOULD be invited to become a Maintainer.
+4. Administrators SHOULD remove Maintainers who are inactive for an extended period of time, or who repeatedly fail to apply this process accurately.
+5. Administrators SHOULD block or ban "bad actors" who break the code of conduct. This should be done after seeking a discussion. A bad actor is someone who repeatedly ignores the rules and culture of the project, who is needlessly argumentative or hostile, or who is offensive, and who is unable to self-correct their behavior when asked to do so by others.
+
+## Sources and License
+
+This Specification is free software; you can redistribute it and/or modify it under the terms of the GNU General Public License as published by the Free Software Foundation; either version 3 of the License, or (at your option) any later version.
+
+This Specification is distributed in the hope that it will be useful, but WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License for more details.
+
+You should have received a copy of the GNU General Public License along with this program; if not, see http://www.gnu.org/licenses.
+
+This contribution guide is based upon the [Collective Code Construction Contract (C4.2)](https://rfc.zeromq.org/spec:42).