Refactor rustic_core API & add more documentation to rustic_core

[aawsome]

closes rustic-rs/rustic_core#8

TODO

• write concise entry comment in rustic_core/Readme.md (factored out into docs: Update Readmes #820)
• write concise entry comment in lib.rs
• recheck imports and library API
  • regenerate public API data (see Justfile)
• document errors in fallible functions and methods
• document # Type Parameters for Repository and others
• fully document methods and functions in public API

Moved to umbrella issue

• remove unwraps out of public API (e.g. /commands/copy::copy()) and in general out of the core library
• Replace logging with error handling, there shouldn't be error! anywhere in the API of the library, they should be actual errors

[simonsan]

Can you tag me, when I should review? Force-pushing makes it relatively hard to follow changes between each read.

[aawsome]

@simonsan It is far from perfect, but I think it is a good start which would enable us to publish a first version of the rustic_core crate.
I am very looking forward to feedback!

[simonsan]

@simonsan It is far from perfect, but I think it is a good start which would enable us to publish a first version of the rustic_core crate. I am very looking forward to feedback!

Will take some time today/the next days to go through it!

[simonsan]

First part (please don't force push from now on, otherwise my progress will be lost for the rest of the files).

[aawsome]

I just force-pushed the last commit to correct compile problems from the suggestions (last_modified_node wasn't used at all places)

[simonsan]

Second review batch, came until /src/repofile/indexfile.rs 👍🏽

Maybe you can go through the imports again, because in most files these are wrong (see some comments).

Note: Still three open issues from last review.

[simonsan]

Gave this a P-high as I think we should merge and focus on this big PR before merging others. So we don't open more than one construction site at once.

[simonsan]

Fixed all or most of the issue I could spot.

Some traits need further documentation:

pub trait IndexedTree

pub trait IndexedIds: IndexedTree {}

pub trait IndexedFull: IndexedIds {}

Also, a good search string: // TODO: Add documentation

[simonsan]

I also added the following, I can factor that out into (a) separate PR(s) if you want to:

Factored out:

PR #820:

• testing, releasing, and development guide
• text changes to rustic and rustic_core readmes
• graphical and layout changes incl. the addition of a logo
• changes to CONTRIBUTING.md

PR #821:

• fail fast for the matrix CI

PR #822:

• Update the manifests to prepare for rustic_core release

[aawsome]

This PR unfortunately got a bit messy. I started several times to work on it but always ran out of time (or motivation, to be honest) to further continue.. This is something we have to improve - make smaller PRs which stay reviewable!

So, today another approach.. I removed quite some commits from you @simonsan - the ones which you have factored out and I hope I didn't accidentially remove something important.

[aawsome]

I also fixed some non-running tests and squashed the commits...

[aawsome]

I won't say that this PR is finishing all attempts to define&document the rustic_core API, but it improves it a lot and is a big PR which always stands in the way if we don't merge it.

As it looks very good from my side, I'll merge it to make the way open for (hopefully much smaller/ more local) further PRs which even more improve it.

[simonsan]

This is something we have to improve - make smaller PRs which stay reviewable!

I agree, though for lacking documentation it's pretty reasonable I think. In the end, it was technical debt that we had to work on which (IMHO, as expected) turned out to be quite a huge PR. We should keep that in mind for future PRs regarding the scope crates/rustic_core/* to always add documentation so we are not increasing that debt again.