-
Notifications
You must be signed in to change notification settings - Fork 123
[new-backend] docs #4484
[new-backend] docs #4484
Conversation
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
@markus2330 There are some open questions. Input is welcome.
Also @atmaxinger I made up some names for the hooks for notifications and spec. If you have better ideas go ahead and suggest them. Also, if you work on spec, you may be interesting in comment about metaspec:/
/spec/remove
.
doc/dev/kdb-operations.md
Outdated
|
||
Additionally, plugins may implement `elektra<Plugin>Commit` and `elektra<Plugin>Error`. | ||
<!-- TODO: should commit and error really be separate? With the new elektraPluginGetPhase they could just be part of set... --> |
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
@markus2330 What do you think? IMO commit
/error
should be merged back into set
.
The current solution just creates unnecessary extra code in both libelektra-kdb
libelektra/src/libs/elektra/kdb.c
Lines 2028 to 2035 in fac8496
enum KdbSetFn | |
{ | |
KDB_SET_FN_SET, | |
KDB_SET_FN_COMMIT, | |
KDB_SET_FN_ERROR, | |
}; | |
static bool runSetPhase (KeySet * backends, Key * parentKey, const char * phase, bool blockErrors, enum KdbSetFn function) |
and backend plugins
libelektra/src/plugins/backend/backend.c
Lines 562 to 589 in fac8496
static int runPluginCommit (Plugin * plugin, KeySet * ks, Key * parentKey) | |
{ | |
// TODO: provide way to access kdbCommit and name without kdbprivate.h | |
ksRewind (ks); | |
int ret = plugin->kdbCommit (plugin, ks, parentKey); | |
if (ret == ELEKTRA_PLUGIN_STATUS_ERROR) | |
{ | |
if (keyGetMeta (parentKey, "error") == NULL) | |
{ | |
addGenericError (parentKey, "kdbCommit", plugin->name); | |
} | |
} | |
return ret; | |
} | |
static int runPluginListCommit (PluginList * plugins, KeySet * ks, Key * parentKey) | |
{ | |
for (PluginList * cur = plugins; cur != NULL; cur = cur->next) | |
{ | |
if (runPluginCommit (cur->plugin, ks, parentKey) == ELEKTRA_PLUGIN_STATUS_ERROR) | |
{ | |
return ELEKTRA_PLUGIN_STATUS_ERROR; | |
} | |
} | |
return ELEKTRA_PLUGIN_STATUS_SUCCESS; | |
} | |
int ELEKTRA_PLUGIN_FUNCTION (commit) (Plugin * plugin, KeySet * ks, Key * parentKey) |
(there is more and it is and is all basically copy-paste from the set code)
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
This is up to @flo91 to decide. I thought it is a good idea to have commit+error, in particular for the database backend.
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
I thought it is a good idea to have commit+error, in particular for the database backend.
The phases still exist. The only question is whether we really need separate functions. Like I said it creates quite a bit of code duplication in many cases (because C doesn't have templates, generic, etc.).
If we take the backend
plugin as the example, it basically a decision between what we have now and moving this
libelektra/src/plugins/backend/backend.c
Lines 600 to 611 in fac8496
if (strcmp (phase, KDB_SET_PHASE_PRE_COMMIT) == 0) | |
{ | |
return runPluginListCommit (handle->setPositions.precommit, ks, parentKey); | |
} | |
else if (strcmp (phase, KDB_SET_PHASE_COMMIT) == 0) | |
{ | |
return runPluginCommit (handle->setPositions.commit, ks, parentKey); | |
} | |
else if (strcmp (phase, KDB_SET_PHASE_POST_COMMIT) == 0) | |
{ | |
return runPluginListCommit (handle->setPositions.postcommit, ks, parentKey); | |
} |
and this
libelektra/src/plugins/backend/backend.c
Lines 660 to 671 in fac8496
if (strcmp (phase, KDB_SET_PHASE_PRE_ROLLBACK) == 0) | |
{ | |
return runPluginListError (handle->setPositions.prerollback, ks, parentKey); | |
} | |
else if (strcmp (phase, KDB_SET_PHASE_ROLLBACK) == 0) | |
{ | |
return runPluginError (handle->setPositions.rollback, ks, parentKey); | |
} | |
else if (strcmp (phase, KDB_SET_PHASE_POST_ROLLBACK) == 0) | |
{ | |
return runPluginListError (handle->setPositions.postrollback, ks, parentKey); | |
} |
into the if-else
chain in the set function (and replacing run*Commit
/run*Error
with run*Set
).
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
I don't think that code duplication in backend plugins should be the decisive factor here. IMHO more important is the clarity in resolvers. But I am open to both ways, having plugins with only open/get/set/close is more elegant.
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
Another (more dramatic) option would be to add the current phase as a 4th parameter to the get
and set
functions of plugins:
int elektraFooGet (Plugin * handle, ElektraGetPhase phase, KeySet * ks, Key * parentKey);
int elektraFooSet (Plugin * handle, ElektraSetPhase phase, KeySet * ks, Key * parentKey);
The it's also quite clear that phase
should probably be handled in some way.
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
No, the phase can be communicated via the plugin handle better. Not every plugin is interested in the phase. In any case: there is doc/decisions/commit_function.md, which needs an update.
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
there is doc/decisions/commit_function.md, which needs an update.
Sure, but do we want a separate commit/error function or not. Because if not, I would just remove the file. I can create a new kdb_phases.md
decisison, but I'm not sure we need it. It's already implemented and it is documented in doc/dev/backend-plugins.md
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
Great work, hope to see this docu updates soon in new-backend!
doc/dev/kdb-operations.md
Outdated
|
||
Additionally, plugins may implement `elektra<Plugin>Commit` and `elektra<Plugin>Error`. | ||
<!-- TODO: should commit and error really be separate? With the new elektraPluginGetPhase they could just be part of set... --> |
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
I don't think that code duplication in backend plugins should be the decisive factor here. IMHO more important is the clarity in resolvers. But I am open to both ways, having plugins with only open/get/set/close is more elegant.
@markus2330 I didn't have time to incorporate your review yet. But I did now look through most of the docs and removed some more things. I didn't remove much and instead added clear warnings ("Outdated"). All these files should be updated before the release. I didn't remove them because they are all still mostly correct and I didn't want to rewrite them all (because just removing something the middle probably creates more confusion). I didn't really look closely at the ALLCAPS.md files, since they all seems mostly unrelated to the new-backend changes. For the manpages (especially Another big reason why I removed so little is: I think the old stuff can be used as reference for the person writing the updated docs. Only the outdated parts really need to be replaced. |
I think it is urgent as this PR we definitely need before merging new-backend. And FLOSS PRs are coming soon.
Thank you very much 🥇 🎆 Will have a look soon. Or is it better we simply merge it and I'll directly review the new-backend PR?
Please also add TODO NEW-BACKEND to make it easier to grep for it. (Warning could be ok to release.)
Yes, needs to be decided case-per-case.
Probably fine.
It is also enough if you mark the whole file for now. But all outdated content should be marked.
As already said, you need to write most of the new-backend-specific docu as nobody else knows the details. |
Do you have a specific date? I'll try to incorporate the review today/tomorrow. And I'll merge IMO we should just merge what is there in
Again I don't know when the deadline is (i.e. when FLOSS needs things merged). But if you really want to review the entire #4187, better start right now. It is big and if the review goes like most of our reviews, there will be extra discussions...
Will do
NO. There is already lots of docs for the new-backend changes: Based on those docs, many of the other less low-level docs can easily be updated by other people. For example, AFAICT There are also multiple other people implementing things for |
e842fe3
to
2df1033
Compare
@markus2330 I have now updated and rebased this PR. Please to a quick, cursory check and merge the PR, unless there is some really major issue. I'll do more minor update in another PR |
I merged this PR since there is still #4187 which can still be reviewed. |
No, it is asap. People may fork their repo any time.
I fully agree!
Thank you! ❤️
E.g. doc/dev/kdb-operations.md is a useful description how to implement a backend. But there are many other viewpoints, e.g. the algorithms etc. which are not yet documented. We need easier understandable docu for new contributors, at least at the level as we had before.
It isn't a perfect match for anyone, as it is a huge left-over and there cannot be a thesis about "finishing others peoples job". Anyway, I am very grateful for your amazing&huge contributions on the most important topics. |
The problem is it seems we disagree about the definition of "ASAP". IMO ASAP is basically now (maybe when I have disabled the failing tests). I think you want a bit more work done, or at least complete your review. I understand that, but any delay will lead to people starting to work on
I have now also updated the doxygen docs for
Of course, but if everyone does a bit, it's much easier for everyone. |
Basics
These points need to be fulfilled for every PR:
(added as entry in
doc/news/_preparation_next_release.md
whichcontains
_(my name)_
)Please always add something to the release notes.
(first line should have
module: short statement
syntax)close #X
, are in the commit messages.doc/news/_preparation_next_release.md
scripts/dev/reformat-all
If you have any troubles fulfilling these criteria, please write
about the trouble as comment in the PR. We will help you.
But we cannot accept PRs that do not fulfill the basics.
Checklist
Check relevant points but please do not remove entries.
For docu fixes, spell checking, and similar none of these points below
need to be checked.
(not in the PR description)
Review
Reviewers will usually check the following:
Labels
If you are already Elektra developer:
say that everything is ready to be merged.