Rewrite contributing.md (#760)

* Rephrase contributing.md
* add a changelog entry.

.vale.ini

@@ -0,0 +1,19 @@
+StylesPath = docs/styles
+MinAlertLevel = warning
+Vocab = Manifolds
+
+MinAlertLevel = suggestion
+
+Packages = Google, write-good
+
+[*.md]
+BasedOnStyles = Vale, Google, write-good
+
+[NEWS.md, CONTRIBUTING.md]
+BasedOnStyles = Vale, Google
+Google.Will = false ; given format and really with intend a _will_
+Google.Headings = false ; some might jeally ahabe [] in their headers
+
+
+[*.jl]
+BasedOnStyles = Vale, Google, write-good

CONTRIBUTING.md

@@ -5,80 +5,100 @@ Any contribution is appreciated and welcome.
 
 The following is a set of guidelines to [`Manifolds.jl`](https://juliamanifolds.github.io/Manifolds.jl/).
 
-#### Table of Contents
+#### Table of contents
 
-- [Contributing to `Manifolds.jl`](#contributing-to-manifoldsjl)
-      - [Table of Contents](#table-of-contents)
-  - [I just have a question](#i-just-have-a-question)
-  - [How can I file an issue?](#how-can-i-file-an-issue)
-  - [How can I contribute?](#how-can-i-contribute)
-    - [Add a missing method](#add-a-missing-method)
-    - [Provide a new manifold](#provide-a-new-manifold)
-    - [Code style](#code-style)
+* [Contributing to `Manifolds.jl`](#contributing-to-manifoldsjl)
+  * [Table of Contents](#table-of-contents)
+  * [How to ask a question](#how-to-ask-a-question)
+  * [How to file an issue](#How-to-file-an-issue)
+  * [How to contribute](#How-to-contribute)
+    * [Add a missing method](#add-a-missing-method)
+    * [Provide a new manifold](#provide-a-new-manifold)
+  * [Code style](#Code-style)
 
-## I just have a question
+## How to ask a question
 
-The developers can most easily be reached in the Julia Slack channel [#manifolds](https://julialang.slack.com/archives/CP4QF0K5Z).
+You can most easily reach the developers in the Julia Slack channel [#manifolds](https://julialang.slack.com/archives/CP4QF0K5Z).
 You can apply for the Julia Slack workspace [here](https://julialang.org/slack/) if you haven't joined yet.
 You can also ask your question on [discourse.julialang.org](https://discourse.julialang.org).
 
-## How can I file an issue?
+## How to file an issue
 
-If you found a bug or want to propose a feature, we track our issues within the [GitHub repository](https://github.com/JuliaManifolds/Manifolds.jl/issues).
+If you found a bug or want to propose a feature, issues are tracked within the [GitHub repository](https://github.com/JuliaManifolds/Manifolds.jl/issues).
 
-## How can I contribute?
+## How to contribute
+
+### Overview of resources
+
+* [`ManifoldsBase.jl`](https://juliamanifolds.github.io/ManifoldsBase.jl/stable/) documents the [main design principles](https://juliamanifolds.github.io/ManifoldsBase.jl/stable/design/) for Riemannian manifolds in the [`JuliaManifolds`](https://github.com/JuliaManifolds) ecosystem
+* The [main set of functions](https://juliamanifolds.github.io/ManifoldsBase.jl/stable/functions/) serves as a guide, showing which functions the Library of manifolds in `Manifolds.jl` provides.
+* A [tutorial on how to define a manifold](https://juliamanifolds.github.io/ManifoldsBase.jl/stable/tutorials/define-a-manifold/) serves as a starting point on how to introduce a new manifold
+* The [changelog](https://juliamanifolds.github.io/Manifolds.jl/stable/misc/NEWS.html) documents all additions and changes. The corresponding file to edit is the [NEWS.md](https://github.com/JuliaManifolds/Manifolds.jl/blob/master/NEWS.md)
+* This file `CONTRIBUTING.md`  provides a technical introduction to contributing to `Manifolds.jl`
 
 ### Add a missing method
 
-Not all methods from our interface [`ManifoldsBase.jl`](https://juliamanifolds.github.io/ManifoldsBase.jl/) have been implemented for every manifold.
-If you notice a method missing and can contribute an implementation, please do so!
-Even providing a single new method is a good contribution.
+Within `Manifolds.jl`, there might be manifolds, that are only partially define the list of methods from the interface given in [`ManifoldsBase.jl`](https://juliamanifolds.github.io/ManifoldsBase.jl/).
+If you notice a missing method but are aware of an algorithm or theory about it,
+contributing the method is welcome.
+Even just the smallest function is a good contribution.
 
 ### Provide a new manifold
 
 A main contribution you can provide is another manifold that is not yet included in the
 package.
-A manifold is a concrete type of [`AbstractManifold`](https://juliamanifolds.github.io/ManifoldsBase.jl/stable/types.html#ManifoldsBase.AbstractManifold) from [`ManifoldsBase.jl`](https://juliamanifolds.github.io/ManifoldsBase.jl/stable/types.html#The-Manifold-interface).
-This package also provides the main set of functions a manifold can/should implement.
-Don't worry if you can only implement some of the functions.
-If the application you have in mind only requires a subset of these functions, implement those.
-The [`ManifoldsBase.jl` interface](https://juliamanifolds.github.io/ManifoldsBase.jl/stable/types.html#The-Manifold-interface) provides concrete error messages for the remaining unimplemented functions.
+A manifold is a concrete subtype of [`AbstractManifold`](https://juliamanifolds.github.io/ManifoldsBase.jl/stable/types.html#ManifoldsBase.AbstractManifold) from [`ManifoldsBase.jl`](https://juliamanifolds.github.io/ManifoldsBase.jl/stable/types.html#The-Manifold-interface).
+A [tutorial on how to define a manifold](https://juliamanifolds.github.io/ManifoldsBase.jl/stable/tutorials/implement-a-manifold/) helps to get started on a new manifold.
+Every new manifold is welcome, even if you only add a few functions,
+for example when your use case for now does not require more features.
 
-One important detail is that the interface usually provides an in-place as well as a non-mutating variant
+One important detail is that the interface provides an in-place as well as a non-mutating variant
 See for example [exp!](https://juliamanifolds.github.io/ManifoldsBase.jl/stable/functions.html#ManifoldsBase.exp!-Tuple{AbstractManifold, Any, Any, Any}) and [exp](https://juliamanifolds.github.io/ManifoldsBase.jl/stable/functions.html#Base.exp-Tuple{AbstractManifold, Any, Any}).
-The non-mutating one (e.g. `exp`) always falls back to use the in-place one, so in most cases it should
-suffice to implement the in-place one (e.g. `exp!`).
+The non-mutating one, `exp`, always falls back to allocating the according memory,
+here a point on the manifold, to then call the in-place variant.
+This way it suffices to provide the in-place variant, `exp!`.
+The allocating variant only needs to defined if a more efficient version
+than the default is available.
 
 Note that since the first argument is _always_ the [`AbstractManifold`](https://juliamanifolds.github.io/ManifoldsBase.jl/stable/types.html#ManifoldsBase.AbstractManifold), the mutated argument is always the second one in the signature.
-In the example we have `exp(M, p, X, t)` for the exponential map and `exp!(M, q, p, X, t)` for the in-place one, which stores the result in `q`.
+In the example there are `exp(M, p, X, t)` for the exponential map that allocates
+its result `q`, and `exp!(M, q, p, X, t)` for the in-place one, which computes and returns the `q`.
 
-On the other hand, the user will most likely look for the documentation of the non-mutating version, so we recommend adding the docstring for the non-mutating one, where all different signatures should be collected in one string when reasonable.
-This can best be achieved by adding a docstring to the method with a general signature with the first argument being your manifold:
+Since a user probably looks for the documentation on the allocating variant,
+we recommend to attach the documentation string to this variant, mentioning all
+possible function signatures including the mutating one.
+You can best achieve this by adding a documentation string to the method with a general signature with the first argument being your manifold:
 
-````julia
+```julia
 struct MyManifold <: AbstractManifold end
 
-@doc raw"""
+@doc """
     exp(M::MyManifold, p, X)
+    exp!(M::MyManifold, q, p, X)
 
-Describe the function.
+Describe the function, its input and output as well as a mathematical formula.
 """
 exp(::MyManifold, ::Any...)
-````
+```
+
+You can also save the string to a variable, for example `_doc_myM_exp` and attach it to both functions
 
-### Code style
+## Code style
 
-We try to follow the [documentation guidelines](https://docs.julialang.org/en/v1/manual/documentation/) from the Julia documentation as well as [Blue Style](https://github.com/invenia/BlueStyle).
-We run [`JuliaFormatter.jl`](https://github.com/domluna/JuliaFormatter.jl) on the repo in the way set in the `.JuliaFormatter.toml` file, which enforces a number of conventions consistent with the Blue Style.
+Please follow the [documentation guidelines](https://docs.julialang.org/en/v1/manual/documentation/) from the Julia documentation as well as [Blue Style](https://github.com/invenia/BlueStyle).
+Run [`JuliaFormatter.jl`](https://github.com/domluna/JuliaFormatter.jl) on the repository running `using JuliaFormatter; format(".")` on the main folder of the project.
 
-We also follow a few internal conventions:
+Please follow a few internal conventions:
 
-- It is preferred that the `AbstractManifold`'s struct contain a reference to the general theory.
-- Any implemented function should be accompanied by its mathematical formulae if a closed form exists.
-- Within the source code of one manifold, the type of the manifold should be the first element of the file, and an alphabetical order of the functions is preferable.
-- The above implies that the in-place variant of a function follows the non-mutating variant.
-- There should be no dangling `=` signs.
-- Always add a newline between things of different types (struct/method/const).
-- Always add a newline between methods for different functions (including in-place/nonmutating variants).
-- Prefer to have no newline between methods for the same function; when reasonable, merge the docstrings.
-- All `import`/`using`/`include` should be in the main module file.
+* Please include a description of the manifold and a reference to the general theory in the `struct` of your manifold that inherits from `AbstractManifold`'.
+* Include the mathematical formulae for any implemented function if a closed form exists.
+* Within the source code of one manifold, the `struct` the manifold should be the first element of the file.
+* an alphabetical order of functions in every file is preferable.
+* The preceding implies that the mutating variant of a function follows the non-mutating variant.
+* There should be no dangling `=` signs.
+* Always add a newline between things of different types (`struct`/method/const).
+* Always add a newline between methods for different functions (including allocating and in-place variants).
+* Prefer to have no newline between methods for the same function; when reasonable, merge the documentation string.
+* Always document all input variables and keyword arguments
+* if possible provide both mathematical formulae and literature references using [DocumenterCitations.jl](https://juliadocs.org/DocumenterCitations.jl/stable/) and BibTeX where possible
+* All `import`/`using`/`include` should be in the main module file.

NEWS.md

@@ -5,6 +5,12 @@ All notable changes to this project will be documented in this file.
 The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/),
 and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
+## [0.10.5] – unreleased
+
+### Changed
+
+* rewrote the `CONTRIBUTING.md` and adapt it to todays links and references.
+
 ## [0.10.4] - 2024-10-20
 
 ### Added

docs/styles/Google/AMPM.yml

@@ -0,0 +1,9 @@
+extends: existence
+message: "Use 'AM' or 'PM' (preceded by a space)."
+link: 'https://developers.google.com/style/word-list'
+level: error
+nonword: true
+tokens:
+  - '\d{1,2}[AP]M'
+  - '\d{1,2} ?[ap]m'
+  - '\d{1,2} ?[aApP]\.[mM]\.'

docs/styles/Google/Acronyms.yml

@@ -0,0 +1,64 @@
+extends: conditional
+message: "Spell out '%s', if it's unfamiliar to the audience."
+link: 'https://developers.google.com/style/abbreviations'
+level: suggestion
+ignorecase: false
+# Ensures that the existence of 'first' implies the existence of 'second'.
+first: '\b([A-Z]{3,5})\b'
+second: '(?:\b[A-Z][a-z]+ )+\(([A-Z]{3,5})\)'
+# ... with the exception of these:
+exceptions:
+  - API
+  - ASP
+  - CLI
+  - CPU
+  - CSS
+  - CSV
+  - DEBUG
+  - DOM
+  - DPI
+  - FAQ
+  - GCC
+  - GDB
+  - GET
+  - GPU
+  - GTK
+  - GUI
+  - HTML
+  - HTTP
+  - HTTPS
+  - IDE
+  - JAR
+  - JSON
+  - JSX
+  - LESS
+  - LLDB
+  - NET
+  - NOTE
+  - NVDA
+  - OSS
+  - PATH
+  - PDF
+  - PHP
+  - POST
+  - RAM
+  - REPL
+  - RSA
+  - SCM
+  - SCSS
+  - SDK
+  - SQL
+  - SSH
+  - SSL
+  - SVG
+  - TBD
+  - TCP
+  - TODO
+  - URI
+  - URL
+  - USB
+  - UTF
+  - XML
+  - XSS
+  - YAML
+  - ZIP

docs/styles/Google/Colons.yml

@@ -0,0 +1,8 @@
+extends: existence
+message: "'%s' should be in lowercase."
+link: 'https://developers.google.com/style/colons'
+nonword: true
+level: warning
+scope: sentence
+tokens:
+  - ':\s[A-Z]'

docs/styles/Google/Contractions.yml

@@ -0,0 +1,30 @@
+extends: substitution
+message: "Use '%s' instead of '%s'."
+link: 'https://developers.google.com/style/contractions'
+level: suggestion
+ignorecase: true
+action:
+  name: replace
+swap:
+  are not: aren't
+  cannot: can't
+  could not: couldn't
+  did not: didn't
+  do not: don't
+  does not: doesn't
+  has not: hasn't
+  have not: haven't
+  how is: how's
+  is not: isn't
+  it is: it's
+  should not: shouldn't
+  that is: that's
+  they are: they're
+  was not: wasn't
+  we are: we're
+  we have: we've
+  were not: weren't
+  what is: what's
+  when is: when's
+  where is: where's
+  will not: won't

docs/styles/Google/DateFormat.yml

@@ -0,0 +1,9 @@
+extends: existence
+message: "Use 'July 31, 2016' format, not '%s'."
+link: 'https://developers.google.com/style/dates-times'
+ignorecase: true
+level: error
+nonword: true
+tokens:
+  - '\d{1,2}(?:\.|/)\d{1,2}(?:\.|/)\d{4}'
+  - '\d{1,2} (?:Jan(?:uary)?|Feb(?:ruary)?|Mar(?:ch)?|Apr(?:il)|May|Jun(?:e)|Jul(?:y)|Aug(?:ust)|Sep(?:tember)?|Oct(?:ober)|Nov(?:ember)?|Dec(?:ember)?) \d{4}'

docs/styles/Google/Ellipses.yml

@@ -0,0 +1,9 @@
+extends: existence
+message: "In general, don't use an ellipsis."
+link: 'https://developers.google.com/style/ellipses'
+nonword: true
+level: warning
+action:
+  name: remove
+tokens:
+  - '\.\.\.'

docs/styles/Google/EmDash.yml

@@ -0,0 +1,13 @@
+extends: existence
+message: "Don't put a space before or after a dash."
+link: "https://developers.google.com/style/dashes"
+nonword: true
+level: error
+action:
+  name: edit
+  params:
+    - trim
+    - " "
+tokens:
+  - '\s[—–]\s'
+

docs/styles/Google/Exclamation.yml

@@ -0,0 +1,12 @@
+extends: existence
+message: "Don't use exclamation points in text."
+link: "https://developers.google.com/style/exclamation-points"
+nonword: true
+level: error
+action:
+  name: edit
+  params:
+    - trim_right
+    - "!"
+tokens:
+  - '\w+!(?:\s|$)'

docs/styles/Google/FirstPerson.yml

@@ -0,0 +1,13 @@
+extends: existence
+message: "Avoid first-person pronouns such as '%s'."
+link: 'https://developers.google.com/style/pronouns#personal-pronouns'
+ignorecase: true
+level: warning
+nonword: true
+tokens:
+  - (?:^|\s)I\s
+  - (?:^|\s)I,\s
+  - \bI'm\b
+  - \bme\b
+  - \bmy\b
+  - \bmine\b

docs/styles/Google/Gender.yml

@@ -0,0 +1,9 @@
+extends: existence
+message: "Don't use '%s' as a gender-neutral pronoun."
+link: 'https://developers.google.com/style/pronouns#gender-neutral-pronouns'
+level: error
+ignorecase: true
+tokens:
+  - he/she
+  - s/he
+  - \(s\)he