From eb682d76e8749194658336169c36fe774c939b49 Mon Sep 17 00:00:00 2001 From: Matthias Beyer Date: Fri, 15 Jun 2018 22:07:13 +0200 Subject: [PATCH 01/14] Prettify error messages --- bin/domain/imag-bookmark/src/main.rs | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) diff --git a/bin/domain/imag-bookmark/src/main.rs b/bin/domain/imag-bookmark/src/main.rs index 3438ee78..2741e898 100644 --- a/bin/domain/imag-bookmark/src/main.rs +++ b/bin/domain/imag-bookmark/src/main.rs @@ -94,7 +94,7 @@ fn add(rt: &Runtime) { let mut collection = BookmarkCollectionStore::get(rt.store(), &coll) .map_err_trace_exit_unwrap(1) - .ok_or(BE::from(format!("No BookmarkcollectionStore '{}' found", coll))) + .ok_or(BE::from(format!("No bookmark collection '{}' found", coll))) .map_err_trace_exit_unwrap(1); for url in scmd.values_of("urls").unwrap() { // unwrap saved by clap @@ -135,7 +135,7 @@ fn list(rt: &Runtime) { let collection = BookmarkCollectionStore::get(rt.store(), &coll) .map_err_trace_exit_unwrap(1) - .ok_or(BE::from(format!("No BookmarkcollectionStore '{}' found", coll))) + .ok_or(BE::from(format!("No bookmark collection '{}' found", coll))) .map_err_trace_exit_unwrap(1); let links = collection.links(rt.store()).map_err_trace_exit_unwrap(1); @@ -157,7 +157,7 @@ fn remove(rt: &Runtime) { let mut collection = BookmarkCollectionStore::get(rt.store(), &coll) .map_err_trace_exit_unwrap(1) - .ok_or(BE::from(format!("No BookmarkcollectionStore '{}' found", coll))) + .ok_or(BE::from(format!("No bookmark collection '{}' found", coll))) .map_err_trace_exit_unwrap(1); for url in scmd.values_of("urls").unwrap() { // enforced by clap From 33789a0da8c14a9acbcf0ee7cbfeccc147496517 Mon Sep 17 00:00:00 2001 From: Matthias Beyer Date: Mon, 11 Jun 2018 13:48:33 -0300 Subject: [PATCH 02/14] Change contributing documentation For after we leave github, the documentation on how to contribute has to be adjusted. This patch does this. --- doc/src/09010-contributing.md | 53 ++++------------------------------- 1 file changed, 6 insertions(+), 47 deletions(-) diff --git a/doc/src/09010-contributing.md b/doc/src/09010-contributing.md index 277c0327..1a1dbc66 100644 --- a/doc/src/09010-contributing.md +++ b/doc/src/09010-contributing.md @@ -7,10 +7,6 @@ All contributors agree to the by contributing to imag. -## Without Github - -Contributing without a github account is perfectly fine and actually encouraged -as we try to move away from github step by step. Feel free to contact [us via our mailinglist](http://imag-pim.org/mailinglist/) and/or submit patches via mail (use `git format-patch` and `git send-email`, always add a cover letter to describe your submission). @@ -22,25 +18,11 @@ By adding that line, you agree to our If you do not add the "Signed-off-by: " line, I reserve the right to kindly reject your patch. -Once _I am_ okay with your patchset, I will -submit it as PR in the github repository (as long as we're using github), -so CI can test it. -I might come back to you if something broke in CI or someone has a suggestion -how to improve your PR. I will keep you as author of the commits. +Make sure to test-compile your patchset and, if available, run tests. ## Finding an issue -Finding an issue is simple: We have -[a special label in our issues section](https://github.com/matthiasbeyer/imag/issues?q=is%3Aissue+is%3Aopen+label%3Acomplexity%2Feasy) -for easy-to-solve issues. You can start there, don't hesitate to ask questions -if you do not understand the issue comment! -If there are currently no issues with that tag, just browse the issues or the -code... you'll always find things to improve! - -Also, if you've found bugs or outdated stuff in our documentation, feel free to -file issues about them or even better: Write a pull request to fix them! - ## Prerequisites @@ -71,36 +53,13 @@ All dependencies are installable with the nix package manager by using a ## Commit guidelines -Please don't refer to issues or PRs from inside a commit message, if possible. -Make sure your PR does not contain "Fixup" commits when publishing it, but feel -free to push "Fixup" commits in the review process. We will ask you to clean -your history before merging! If you're submitting via patch-mail, I will do the -fixup squashing myself. If it fails I will come back to you. - -Make sure to prefix your commits with `"doc: "` if you change the documentation. -Do not change document and code in one commit, always separate them. - -If your changes are user-visible (new commandline flags, other semantics in the -commandline, etc), make sure to add a note in the `CHANGELOG.md` file (in the -same commit if it is a simple change). -**If it is a bugfix**, do add the changelog entry in a new commit (best would -be: one commit for a testcase which shows the bug, one commit for the fix, more -if the fix is complicated, and one commit for the changelog entry). -Changelog entries for bug fixes should be extra commits, because backporting -bugfixes gets simpler this way. +Make sure your patchset does not contain "Fixup" commits when publishing it, but feel +free to send "Fixup" commits in the review process. +If squashing fails I will come back to you. We do not follow some official Rust styleguide for our codebase, but we try to -write minimal and readable code. 100 characters per line, as few lines as -possible, avoid noise in the codebase, ... you get it. - -Not all of your commits have to be buildable. But your PR has to be before it -will be merged to master. - - -## Feature branches - -Use feature branches. If you could name them "/", -for example "libimagstore/add-debugging-calls", that would be awesome. +write minimal and readable code. 100 characters per line, avoid noise in the +codebase, ... you get it. ## Code of Conduct From f9294eb07abf9d16ba144dc88652c5af04a3e204 Mon Sep 17 00:00:00 2001 From: Matthias Beyer Date: Mon, 11 Jun 2018 14:55:33 -0300 Subject: [PATCH 03/14] doc: Update README --- doc/README.md | 16 +--------------- 1 file changed, 1 insertion(+), 15 deletions(-) diff --git a/doc/README.md b/doc/README.md index b88d1fd1..00a3bd5b 100644 --- a/doc/README.md +++ b/doc/README.md @@ -3,19 +3,5 @@ This subdirectory contains the documentation of the basic idea behind ``imag''. It is written in Markdown and compiled to both PDF and HTML via pandoc. -# Contributing to this paper - -First, the paper is not build by travis-ci. This means if there are errors, they -will be detected by me only if I build the paper. I know this is not optimal, -but as documented in [70](https://github.com/matthiasbeyer/imag/pull/70), -building the paper in travis would slow down the travis-ci machines too much. - -So if you want to contribute I would like you to build the paper, if you can. -The dependencies you need are listed in the `default.nix` file (you don't need -either nix nor nixos, all of these packages should be available in all major -distros). Make sure you use pandoc `1.10+`. - -Contributing to this paper is done via normal pull requests, RFC-Like. - -That's all to it so far. +Make sure you use pandoc `1.10+` if you want to build the paper. From 6e45727f158ae3dfd89f277305dd787f87c643e8 Mon Sep 17 00:00:00 2001 From: Matthias Beyer Date: Mon, 11 Jun 2018 20:31:14 -0300 Subject: [PATCH 04/14] Update conventions --- doc/src/03010-conventions.md | 23 ++++++++++++++--------- 1 file changed, 14 insertions(+), 9 deletions(-) diff --git a/doc/src/03010-conventions.md b/doc/src/03010-conventions.md index f56edbc9..a6cf4d3e 100644 --- a/doc/src/03010-conventions.md +++ b/doc/src/03010-conventions.md @@ -43,23 +43,24 @@ cross-read it for better understanding of the imag project. ### Library naming -Libraries which provide functionality for entries or the store (most likely -entries or both) should be named "libimagentrything" whereas "thing" stands for +Libraries which provide functionality for entries or the store but no +domain-functionality should be named "libimagentrything" whereas "thing" stands for what the library provides. -All other libraries should be prefixed with "libimag" at least. Most likely, one -will not write such a library but rather a "libimagentrything" library. +All domain libraries should be prefixed with "libimag". + ### Library scope A library should never introduce utility functionality which could be useful for other libraries as well. If there is no such functionality available, the "libimagutil" or "libimagentryutil" might be a place where such a function -would be put. +would go to. If a library has to introduce free functions in its public interface, one should think hard whether this is really necessary. + ### Library error types/kinds Libraries must use "error-chain" to create error types and kinds. @@ -72,6 +73,7 @@ as many error kinds as required. ### Libraries with commandline frontends Libraries with commandline frontends provide end-user functionality. +They are called "domain" libraries. Normally, they depend on one or more "libimagentrything" libraries. They should be named "libimagthing", though. For example: "libimagdiary", "libimagtimetrack" or @@ -83,8 +85,6 @@ If such a library needs to depend on another "libimagthing", for example if whether the functionality could be outsourced to a more general "libimagentrything". -A library which implements a functionality for imag may contain helper functions -for commandline stuff, but that is discouraged. ### Library testing @@ -96,6 +96,11 @@ possible without a lot of effort, but still: more tests = better! The commandline tools are the CLI-frontends for their respective libraries. So `libimagdiary` has a CLI frontend `imag-diary`. -Those CLI frontends use functionality from `libimagrt` to build a consistent -commandline interface. +Those CLI frontends use functionality from `libimagrt` to build a +commandline interface which is consistent with the rest of the ecosystem. + +Commandline interfaces should receive store IDs as positional arguments. +Commandline interfaces should also provide a flag "-I" (that's a big i) which +marks that the store IDs shall be read from stdin and are not passed via the +commandline. From 869f5377f9cfaf52fc44dbfd5e24e8cf826cd287 Mon Sep 17 00:00:00 2001 From: Matthias Beyer Date: Mon, 11 Jun 2018 20:43:33 -0300 Subject: [PATCH 05/14] Update intro --- doc/src/01000-intro.md | 41 +++++++++++++++++++++++------------ doc/src/09010-contributing.md | 2 +- 2 files changed, 28 insertions(+), 15 deletions(-) diff --git a/doc/src/01000-intro.md b/doc/src/01000-intro.md index 76a67b15..ca645b53 100644 --- a/doc/src/01000-intro.md +++ b/doc/src/01000-intro.md @@ -1,17 +1,16 @@ # Introduction {#sec:introduction} This document is the user documentation for imag, the personal -information management suite for the commandline. Besides being a documentation, -it serves also as "roadmap" where this project should go. +information management suite for the commandline. **Basically: This is Hobby stuff. Expect incompleteness, false statements and -generally read with big grain of salt.** +generally read with grain of salt.** If you have any objections, suggestions for improvements, bugs, etc, please file -them. +them (See [@sec:contributing]). A way to reach out to the imag project maintainer(s) is described in the -CONTRIBUTING file of the repository or in this document, in the appropriate -section. +[@sec:contributing] section. + ## The Problem {#sec:intro:problem} @@ -19,20 +18,21 @@ The problem this project tries to solve is to provide a modular commandline application for personal information management. It targets "power users" or "commandline users", uses plain text as a storage -format and tries to be scriptable. +format and tries to be as scriptable as possible. imag offers the ability to link data from different "PIM aspects" (such as -"diary" and "bookmark" for example). +"diary", "contacts" and "bookmark" for example). One major goal of imag is to make the PIM data traverseable and queryable. For example: a wiki article can be linked to an appointment which is linked to a todo which is linked to a note which is linked to a contact. imag wants to offer an all-in-one scriptable modular commandline personal -information management suite for all PIM aspects one can think of. +information management suite for all PIM aspects one could possibly think of. Because imag uses plain text (TOML headers for structured data and plain text which can be rendered using markdown, for example, for continuous text) the user is always able to access their data without the imag tools at hand. + ## The Approach {#sec:intro:approach} The approach "imag" takes on solving this problem is to store content in a @@ -42,8 +42,8 @@ structured data. This can be used to implement a variety of "domain modules" using the store. While content is stored in _one_ place, imag does not duplicate content. imag does not copy or move icalendar files, emails, vcard files, music or -movies to the store, but creates references to the actual files and stores -meta-information in the store. +movies to the store, but tries to remember the actual files are and stores +meta-information about them in the store. Detailed explanation on this approach follows in the chapters of this work. @@ -57,7 +57,7 @@ library of the imag distribution to store content in the store of imag and make it visible to imag this way. This is a technical detail a user does not necessarily need to know, but as imag -is intended for power-users anyways, we could say it fits here. +is intended for power-users anyways, we would say it fits here. ## Alternative Projects {#sec:intro:alternatives} @@ -68,6 +68,19 @@ for the [emacs](https://www.gnu.org/software/emacs/) text editor. There is also [zim](http://zim-wiki.org/), a desktop wiki editor which is intended to be used for a personal wiki. -The difference between imag and the mentioned projects is that imag is not there -yet. Some parts can be used, though it is far away from being feature-complete. +The difference between imag and the mentioned projects is: +* emacs orgmode is (from what I know and see) for _orgabizing_ things. imag is + intended not only for organizing, but also for recording, tracking and + querying. +* zim is a wiki, which could be used for PIM but is not specialized for it. + Recording habits might be possible, but not that simple as with imag + +imag is not there +yet, though. Some parts can be used, though it is far away from being feature-complete. + +In addition: imag is text-editor independent and other tools than imag might be +used to access data stored in the imag store. +For example, one could "grep", "awk" and "sed" entries without much hassle and +even write bash scripts for automatically filling imag entries with data. + diff --git a/doc/src/09010-contributing.md b/doc/src/09010-contributing.md index 1a1dbc66..b5858d7e 100644 --- a/doc/src/09010-contributing.md +++ b/doc/src/09010-contributing.md @@ -1,4 +1,4 @@ -# Contributing to imag +# Contributing to imag {#sec:contributing} So you want to contribute to imag! Thank you, that's awesome! From 58479874044881bfa87c789594bf668431524e8a Mon Sep 17 00:00:00 2001 From: Matthias Beyer Date: Wed, 13 Jun 2018 20:29:29 -0300 Subject: [PATCH 06/14] Remove old statement --- doc/src/05100-lib-contacts.md | 3 --- 1 file changed, 3 deletions(-) diff --git a/doc/src/05100-lib-contacts.md b/doc/src/05100-lib-contacts.md index 2d38b52d..9182ea8c 100644 --- a/doc/src/05100-lib-contacts.md +++ b/doc/src/05100-lib-contacts.md @@ -44,6 +44,3 @@ The architecture of indirections is as follows: ``` -As the library is build upon `libimagentryref`, it does not create a new -subcollection in the store `/contacts`, but uses the infrastructure of -`libimagentryref` which automatically puts all references in `/ref`. From d6a19d8645d4b78a2dc99ca3744ca0f897d8517b Mon Sep 17 00:00:00 2001 From: Matthias Beyer Date: Wed, 13 Jun 2018 20:31:39 -0300 Subject: [PATCH 07/14] Update lib description --- doc/src/05100-lib-diary.md | 11 +++-------- 1 file changed, 3 insertions(+), 8 deletions(-) diff --git a/doc/src/05100-lib-diary.md b/doc/src/05100-lib-diary.md index d9e8d698..43bce9e3 100644 --- a/doc/src/05100-lib-diary.md +++ b/doc/src/05100-lib-diary.md @@ -5,12 +5,7 @@ This library crates implements a full diary. One can have one or more diaries in the store, each diary can have unlimited entries. -### Future plans - -The diary should be able to provide _daily_, _hourly_ and even _minutely_ -diary entries, so one can use the diary as normal "Dear diary, -today..."-diary, or more fine-grained and more like a journal. - -The internal file format as well as the store-path generation for this module is -prepared for such functionality. +The diary provides _daily_, _hourly_ and even _minutely_ +diary entries. For twitter-like log keeping, have a look at "libimaglog", +though. From cb8c511985e8dde6deb68f84b0f0d738981dbe94 Mon Sep 17 00:00:00 2001 From: Matthias Beyer Date: Wed, 13 Jun 2018 20:35:31 -0300 Subject: [PATCH 08/14] Update lib description --- doc/src/05100-lib-entryfilter.md | 3 +-- 1 file changed, 1 insertion(+), 2 deletions(-) diff --git a/doc/src/05100-lib-entryfilter.md b/doc/src/05100-lib-entryfilter.md index 2812db39..8c4a4369 100644 --- a/doc/src/05100-lib-entryfilter.md +++ b/doc/src/05100-lib-entryfilter.md @@ -1,8 +1,7 @@ ## libimagentryfilter Helper library to filter lists of entries by certain predicated. Offers filters -for filtering by header values and other predicates, plus this library offers -logical operants to combine filters. +for filtering by header values and other predicates. A commandline-to-filter DSL is planned for this, so commandline applications can use this to implement a uniform filter interface. From 473f962874ac69ece532a84047fdc465a9526afd Mon Sep 17 00:00:00 2001 From: Matthias Beyer Date: Wed, 13 Jun 2018 20:35:31 -0300 Subject: [PATCH 09/14] Update lib description --- doc/src/05100-lib-entrylink.md | 5 ++--- 1 file changed, 2 insertions(+), 3 deletions(-) diff --git a/doc/src/05100-lib-entrylink.md b/doc/src/05100-lib-entrylink.md index 6c6caff5..70d1dea7 100644 --- a/doc/src/05100-lib-entrylink.md +++ b/doc/src/05100-lib-entrylink.md @@ -1,5 +1,4 @@ ## libimagentrylink -Linking library for linking entries with other entries. Used for "imag-link", -the commandline utility, but intended for use in other binaries and libraries as -well. +Linking library for linking entries with other entries. + From 6ba87a58d18c5ee3b9e3e54b77c97f9cf1675c53 Mon Sep 17 00:00:00 2001 From: Matthias Beyer Date: Wed, 13 Jun 2018 20:36:22 -0300 Subject: [PATCH 10/14] Add 'Known Problems' section --- doc/src/05100-lib-entryref.md | 5 +++++ 1 file changed, 5 insertions(+) diff --git a/doc/src/05100-lib-entryref.md b/doc/src/05100-lib-entryref.md index 37dd8764..b54ba102 100644 --- a/doc/src/05100-lib-entryref.md +++ b/doc/src/05100-lib-entryref.md @@ -47,3 +47,8 @@ Not implemented yet: of pathes, or does depth-first-search rather than breadth-first-search. +### Known problems + +The functionality this library provides fails to work when syncing the imag +store between two devices where the data layout is different on each device. + From c86e4e7db4d933d524f9ab32161663f04566e148 Mon Sep 17 00:00:00 2001 From: Matthias Beyer Date: Tue, 19 Jun 2018 21:07:17 -0300 Subject: [PATCH 11/14] Add documentation for Runtime::init_logger() --- lib/core/libimagrt/src/runtime.rs | 6 ++++++ 1 file changed, 6 insertions(+) diff --git a/lib/core/libimagrt/src/runtime.rs b/lib/core/libimagrt/src/runtime.rs index ed1bdc7e..4e72404d 100644 --- a/lib/core/libimagrt/src/runtime.rs +++ b/lib/core/libimagrt/src/runtime.rs @@ -319,6 +319,12 @@ impl<'a> Runtime<'a> { } /// Initialize the internal logger + /// + /// If the environment variable "IMAG_LOG_ENV" is set, this simply + /// initializes a env-logger instance. Errors are ignored in this case. + /// If the environment variable is not set, this initializes the internal imag logger. On + /// error, this exits (as there is nothing we can do about that) + /// fn init_logger(matches: &ArgMatches, config: Option<&Value>) { use log::set_max_level; use log::set_boxed_logger; From 3bdd5c959be8426ad2a22ab4e3ce1082050917b9 Mon Sep 17 00:00:00 2001 From: Matthias Beyer Date: Tue, 19 Jun 2018 21:23:10 -0300 Subject: [PATCH 12/14] Add documentation to StoreId type --- lib/core/libimagstore/src/storeid.rs | 9 +++++++++ 1 file changed, 9 insertions(+) diff --git a/lib/core/libimagstore/src/storeid.rs b/lib/core/libimagstore/src/storeid.rs index 3d639797..66a94c49 100644 --- a/lib/core/libimagstore/src/storeid.rs +++ b/lib/core/libimagstore/src/storeid.rs @@ -38,6 +38,10 @@ use iter::get::StoreGetIterator; use iter::retrieve::StoreRetrieveIterator; /// The Index into the Store +/// +/// A StoreId object is a unique identifier for one entry in the store which might be present or +/// not. +/// #[derive(Debug, Clone, Hash, Eq, PartialOrd, Ord)] pub struct StoreId { base: Option, @@ -104,6 +108,11 @@ impl StoreId { Ok(base) } + /// Check whether the StoreId exists (as in whether the file exists) + /// + /// # Warning + /// + /// Should be considered deprecated pub fn exists(&self) -> Result { self.clone().into_pathbuf().map(|pb| pb.exists()) } From 54c58547610a02781ed3cc439929f74bc9f7628c Mon Sep 17 00:00:00 2001 From: Matthias Beyer Date: Tue, 19 Jun 2018 21:23:52 -0300 Subject: [PATCH 13/14] Remove unnecessary call --- lib/core/libimagstore/src/storeid.rs | 3 +-- 1 file changed, 1 insertion(+), 2 deletions(-) diff --git a/lib/core/libimagstore/src/storeid.rs b/lib/core/libimagstore/src/storeid.rs index 66a94c49..ddb1443e 100644 --- a/lib/core/libimagstore/src/storeid.rs +++ b/lib/core/libimagstore/src/storeid.rs @@ -157,14 +157,13 @@ impl StoreId { self.id .components() .zip(colls.as_ref().iter()) - .map(|(component, pred_coll)| match component { + .all(|(component, pred_coll)| match component { Component::Normal(ref s) => s .to_str() .map(|ref s| s == &pred_coll.as_ref()) .unwrap_or(false), _ => false }) - .all(|x| x) } pub fn local_push>(&mut self, path: P) { From 8d86af5f15f98893e25b937b2f59534eeda47268 Mon Sep 17 00:00:00 2001 From: Matthias Beyer Date: Wed, 27 Jun 2018 00:43:24 +0200 Subject: [PATCH 14/14] Fix: Use unused result --- bin/domain/imag-habit/src/main.rs | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/bin/domain/imag-habit/src/main.rs b/bin/domain/imag-habit/src/main.rs index 218a0d67..6d195ba8 100644 --- a/bin/domain/imag-habit/src/main.rs +++ b/bin/domain/imag-habit/src/main.rs @@ -197,7 +197,7 @@ fn delete(rt: &Runtime) { } }; - fle + let _ = fle .linked_instances() .map_err_trace_exit_unwrap(1) .trace_unwrap_exit(1)