started updating the docs

Author: Uwe Hernandez Acosta

docs/make.jl

@@ -30,7 +30,15 @@ open(readme_path, "r") do readme_in
 end
 
 pages = [
-  "Home" => "index.md", "Interface" => "10-interface.md", "Reference" => "95-reference.md"
+  "Home" => "index.md",
+  "Interface" => "10-interface.md",
+  "Tutorial" => [
+    "New Four-Vector" => "tutorial/20-new_four_vector.md",
+    "New Coordinate System" => "tutorial/21-new_coord_system.md",
+  ],
+  "Contributors guide" => "90-contributing.md",
+  "Developer docs" => "91-dev_docs.md",
+  "API Reference" => "95-reference.md",
 ]
 
 try

docs/src/10-interface.md

@@ -1,11 +1,14 @@
 # [Interface](@id interface)
 
-This section explains how an object can become a _object with kinematic informations_.
+The main purpose of `LorentzVectorBase` is to provide a general interface for _Julia
+objects with Lorentz vector informations_. This means one implements a minimal set of
+accessor functions, specified by a _coordinate system_, and `LorentzVectorBase` provides
+implementations for a whole suite of additional accessor functions.
 
 ## Definition
 
 A type that adheres to the interface described in this section will be referred to as
-_`KinematicInterface`-compliant_. A package providing such a type will be called _the provider_.
+_`LorentzVectorBase`-compliant_. A package providing such a type will be called _the provider_.
 
 ## Coordinate Systems
 

docs/src/90-contributing.md

@@ -0,0 +1,26 @@
+# [Contributing guidelines](@id contributing)
+
+First of all, thanks for the interest!
+
+We welcome all kinds of contribution, including, but not limited to code, documentation, examples, configuration, issue creating, etc.
+
+Be polite and respectful, and follow the code of conduct.
+
+## Bug reports and discussions
+
+If you think you found a bug, feel free to open an [issue](https://github.com/JuliaHEP/LorentzVectorBase.jl/issues).
+Focused suggestions and requests can also be opened as issues.
+Before opening a pull request, start an issue or a discussion on the topic, please.
+
+## Working on an issue
+
+If you found an issue that interests you, comment on that issue what your plans are.
+If the solution to the issue is clear, you can immediately create a pull request (see below).
+Otherwise, say what your proposed solution is and wait for a discussion around it.
+
+!!! tip
+
+    Feel free to ping us after a few days if there are no responses.
+
+If your solution involves code (or something that requires running the package locally), check the [developer documentation](91-dev_docs.md).
+Otherwise, you can use the GitHub interface directly to create your pull request.

docs/src/91-dev_docs.md

@@ -0,0 +1,141 @@
+# [Developer documentation](@id dev_docs)
+
+!!! note "Contributing guidelines"
+
+    If you haven't, please read the [Contributing guidelines](90-contributing.md) first.
+
+If you want to make contributions to this package that involves code, then this guide is for you.
+
+## First time clone
+
+!!! tip "If you have writing rights"
+
+    If you have writing rights, you don't have to fork. Instead, simply clone and skip ahead. Whenever **upstream** is mentioned, use **origin** instead.
+
+If this is the first time you work with this repository, follow the instructions below to clone the repository.
+
+1. Fork this repo
+2. Clone your repo (this will create a `git remote` called `origin`)
+3. Add this repo as a remote:
+
+    ```bash
+    git remote add upstream https://github.com/JuliaHEP/LorentzVectorBase.jl.git
+    ```
+
+This will ensure that you have two remotes in your git: `origin` and `upstream`.
+You will create branches and push to `origin`, and you will fetch and update your local `main` branch from `upstream`.
+
+## Code Formatting
+
+To maintain code consistency, format your code with:
+
+```julia
+julia --project=.formatting -e 'using Pkg; Pkg.instantiate(); include(".formatting/format_all.jl")'
+```
+
+This ensures adherence to the project's formatting standards.
+
+## Testing
+
+As with most Julia packages, you can just open Julia in the repository folder, activate the environment, and run `test`:
+
+```julia-repl
+julia> # press ]
+pkg> activate .
+pkg> test
+```
+
+## Working on a new issue
+
+We try to keep a linear history in this repo, so it is important to keep your branches up-to-date.
+
+1. Fetch from the remote and fast-forward your local main
+
+    ```bash
+    git fetch upstream
+    git switch main
+    git merge --ff-only upstream/main
+    ```
+
+2. Branch from `main` to address the issue (see below for naming)
+
+    ```bash
+    git switch -c 42-add-answer-universe
+    ```
+
+3. Push the new local branch to your personal remote repository
+
+    ```bash
+    git push -u origin 42-add-answer-universe
+    ```
+
+4. Create a pull request to merge your remote branch into the org main.
+
+### Branch naming
+
+- If there is an associated issue, add the issue number.
+- If there is no associated issue, **and the changes are small**, add a prefix such as "typo", "hotfix", "small-refactor", according to the type of update.
+- If the changes are not small and there is no associated issue, then create the issue first, so we can properly discuss the changes.
+- Use dash separated imperative wording related to the issue (e.g., `14-add-tests`, `15-fix-model`, `16-remove-obsolete-files`).
+
+### Commit message
+
+- Use imperative or present tense, for instance: _Add feature_ or _Fix bug_.
+- Have informative titles.
+- When necessary, add a body with details.
+- If there are breaking changes, add the information to the commit message.
+
+### Before creating a pull request
+
+!!! tip "Atomic git commits"
+
+    Try to create "atomic git commits" (recommended reading: [The Utopic Git History](https://blog.esciencecenter.nl/the-utopic-git-history-d44b81c09593)).
+
+- Make sure the tests pass.
+- Make sure the pre-commit tests pass.
+- Fetch any `main` updates from upstream and rebase your branch, if necessary:
+
+    ```bash
+    git fetch upstream
+    git rebase upstream/main BRANCH_NAME
+    ```
+
+- Then you can open a pull request and work with the reviewer to address any issues.
+
+## Building and viewing the documentation locally
+
+Following the latest suggestions, we recommend using `LiveServer` to build the documentation.
+Here is how you do it:
+
+1. Run `julia --project=docs` to open Julia in the environment of the docs.
+1. If this is the first time building the docs
+    1. Press `]` to enter `pkg` mode
+    1. Run `pkg> dev .` to use the development version of your package
+    1. Press backspace to leave `pkg` mode
+1. Run `julia> using LiveServer`
+1. Run `julia> servedocs()`
+
+## Making a new release
+
+To create a new release, you can follow these simple steps:
+
+- Create a branch `release-x.y.z`
+- Update `version` in `Project.toml`
+- Update the `CHANGELOG.md`:
+    - Rename the section "Unreleased" to "[x.y.z] - yyyy-mm-dd" (i.e., version under brackets, dash, and date in ISO format)
+    - Add a new section on top of it named "Unreleased"
+    - Add a new link in the bottom for version "x.y.z"
+    - Change the "[unreleased]" link to use the latest version - end of line, `vx.y.z ... HEAD`.
+- Create a commit "Release vx.y.z", push, create a PR, wait for it to pass, merge the PR.
+- Go back to main screen and click on the latest commit (link: <https://github.com/JuliaHEP/LorentzVectorBase.jl/commit/main>)
+- At the bottom, write `@JuliaRegistrator register`
+
+After that, you only need to wait and verify:
+
+- Wait for the bot to comment (should take < 1m) with a link to a PR to the registry
+- Follow the link and wait for a comment on the auto-merge
+- The comment should said all is well and auto-merge should occur shortly
+- After the merge happens, TagBot will trigger and create a new GitHub tag. Check on <https://github.com/JuliaHEP/LorentzVectorBase.jl/releases>
+- After the release is create, a "docs" GitHub action will start for the tag.
+- After it passes, a deploy action will run.
+- After that runs, the [stable docs](https://JuliaHEP.github.io/LorentzVectorBase.jl/stable) should be updated. Check them and look for the version number.

docs/src/tutorial/20-new_four_vector.md

@@ -0,0 +1,3 @@
+# [Implement New Four-Vector Type](@id tutorial_new_four_vector)
+
+TBW

docs/src/tutorial/21-new_coord_system.md

@@ -0,0 +1,3 @@
+# [Implement Coordinate System](@id tutorial_new_coord_system)
+
+TBW