Ability to version recipes

[jessechahal]

Is your feature request related to a problem? Please describe.
When I'm working on designing recipes I make incremental changes to them. With each change of the recipe I will take down notes on how it differ's from the previous one (mostly taste but sometimes other things as well such as serving size). It would be nice if there was a method to keep previous versions/checkpoints of a recipe. This way if i find out my new version is worse i could go back. It would also allow me to choose previous variations of a given recipe depending on who the audience/food_eaters are (i.e. extra spicy version, gluten-free version, etc...).

Describe the solution you'd like
Similarly to semantic versioning of software, recipes could also be versioned. Each version can have a commit_comment and unique review notes. Since currently they are essentially text/json files that can be updated at any time maybe a commit/finalize/version/checkpoint/save_as button that would save the current recipe as a separate file and allow you to view or revert back to this previous version. The ideal version of this feature would be something similar to git/svn for recipes but that might be too difficult to do unless there are git/version plugins for files in nextcloud.

Describe alternatives you've considered

• The current method is to copy/paste original version of recipe. If you are only making 1 or 2 new versions/modifications of an existing recipe then its not too big of an issue. But some people create 100+ incremental test changes for any given recipe or maybe even change the recipe slightly every single time for experimentation purposes makes. You cannot just copy/paste in these cases because it becomes very difficult to know what changes/experiments you have tried and which ones you haven't (along with the experiment results).

[jessechahal]

#340 Seems to related when discussing possible implementations of this feature

[christianlupus]

Hello and thank you for your suggestion.

Using git would be some way to do this but I assume this might pose more problems than in the first run. First, it poses assumptions/requirements on the host machine. There is no such thing as a PHP git module. Thus we need to call the system git command or mimic git's behavior manually. Both is not ideal.
Also, git is quite a beast (all the crazy stuff it can do) and we might get more problems than solving it for the average (non-IT) user.

I see two different ways to accomplish this:

1. Overwrite the most current recipe while keeping the historical files separately.
2. Have multiple equally versions of a recipe that you can switch between/select
3. Have multiple versions for viewing but only one for editing

Let me explain a bit what I mean:

No 1 is similar to the behavior of the nextcloud files app. Old versions are saved in a separate folder and you can revert to that state. This might be good for reverting the last change(s) but switching might be more involved. Also the aging of revisions might pose problems.

No 2 and 3 are pretty similar. I am thinking analoguosly to git. No 2 means to have multiple branches that you can commit to (aka change) the individual heads.
In contrast No 3 can be seen as a single head with a set of fixed tags that can be assigned to a certain version. So if you know this version was a good one, just put a tag/name to it. You can check these out for viewing but editing happens always at the ending (think of HEAD).

Which one do you think might fit the requirements most?

I assume you want to generate a new commit/version each time a recipe is changed/saved, right?

[jessechahal]

Well I'm curious about the opinion of other people as well. The recommended solution could change based on if other features are implemented and how they are implemented. One thing I noticed is that currently there is no review system included with recipes. If a review system is implemented how would it work? Would it use/copy the commenting feature that exists in NextCloud Decks (but also include a numerical rating option)? If reviews/rating are implemented the reviews should probably apply to each branch/tag/name/version of a given recipe. That would mean

1. Overwrite the most current recipe while keeping the historical files separately.

would not work.

2. Have multiple equally versions of a recipe that you can switch between/select

This to me sounds like it is the most feature rich. I think if option 2 & 3 are considered equal in difficulty to implement then stick with option 2. If at a later time the feature needs to be restricted or extended this would offer the greatest flexibility.

questions needing answers:

• is there going to be a review/comment system for recipes in the near future. How is it going to work?
  • should the recipes author update/commit messages of a given recipe be treated uniquely from the general review/comment system? Could/should it just be the 1st review/comment of the system?
    • My thoughts: just make the commit/update message the 1st comment/review of the system
• Should recipes always be considered in a finalized/published state? Does this even matter?
  • My thoughts: Usually when developing a recipe you go through steps of changing minor things while noting down the affects of that minor change (possibly including pictures). These changes usually don't need to be shared with others (akin to git commit on a local branch) since the recipe is currently in-progress.
    • To translate this into implementation maybe differentiate between a git branch (in-progress) and a git tag (finalized)?
      • this might make the UI make more sense. When sharing/viewing a recipe you can see the main/original/HEAD and somewhere use a dropdown to select/view different published/finalized/tagged versions. If you are the owner/author of the recipe there could be a separate dropdown to edit a in-progress/unpublished/branch

[christianlupus]

I assume by review system yo mean a system to rate the recipes (good/bad) and not review (like code review, is it correctly written, errorless, ...), right? Well, we are just discussing in PR #342 and #323 how to proceed.

You are most probably right, that option 1 is too restricted. It mainly focuses on the fact that one might want to keep track of the recipes history to allow reverting the changes if they are worse than the original recipe. When working on all recipes, option 2 might most probably be the best.

Regarding comments/reviews in your questions: First, there is currently no system to add comments to recipes. This would be a separate feature request you might want to open. The timing depends a bit on our spare time we can offer and the amount of work do be done before it can be implemented.

One thing you just created by the way was a requirement for a) a commit messages and b) a git-like history. Apart from the fact that I did not understand that in the original post this makes the whole file structure quite more involved.

I'd heavily suggest to split the commit message from any recipe ratings/reviews/comments. The history thing would be something completely independent from the main recipes JSON files (which confirm the schema.org standard). So we would have to keep them apart.

What I would definitively vote for would be not to allow crazy stull like merging, rebasing and the like. It is too technical and a tree-like structure is way easier to handle than a graph.

Also if sharing is to be realized in #120 I definitively would not go with different views of the very same history. Later we might enable this but for now this is bis enough 🙄.

[seyfeb]

I have some questions:

As @christianlupus mentioned a tree-like structure: Is the requirement to support a tree of versions, such that one can have multiple branches of recipes developing in different directions which at some point may even become a new recipe of their own?

Should any saved change create a new version or only if I actively create a “tagged recipe”?

I think that comments and ratings should be handled independently and shouldn’t be the focus of this issue. Also (depending on the answer of the previous question) a commit message has a 1:1 relationship with a recipe version. Comments (might) survive different versions (tbd).

[jessechahal]

The goal from a user perspective was for 2 main things:

• creating recipes
  • creating: the process of developing a new recipe from start to finish
• publishing/versioning multiple versions of a given recipe

I assume by review system yo mean a system to rate the recipes (good/bad) and not review (like code review, is it correctly written, errorless, ...), right? Well, we are just discussing in PR #342 and #323 how to proceed.

Yes I was referring to a rating recipe system. I assumed that a commenting+review system exists. The thing is that while recipes are in development it would be good if the author could make notes about each change. Because of this author notes & code review system & user rating+commenting system & git commits all seemed the same to me.

First, there is currently no system to add comments to recipes. This would be a separate feature request you might want to open.

I realize this would be a separate feature request. I already saw that #323 exists and was just trying to figure out how the rating feature might work/integrate with versioning feature. I originally assumed the rating feature would include a text/comment option but reviewing https://github.com/nextcloud/cookbook/pull/342/commits commit messages this seems like it is not the case. I'll raise that as a separate request should it become necessary.

One thing you just created by the way was a requirement for a) a commit messages and b) a git-like history. Apart from the fact that I did not understand that in the original post this makes the whole file structure quite more involved.

In my 1st post I mentioned "When I'm working on designing recipes I make incremental changes to them." The basic idea was that you could start with a parent recipe (existing recipe or empty), make one or more child recipes (changes to a recipe), each of those children could have one or more child recipes (changes on top of changes), finally one or more descendants could be marked as good alternatives/final recipes that could be used instead of the parent (alternative versions of a recipe). The reason I mentioned commit messages and git-like history is it seemed like the easiest comparison to make on what I was thinking. The most important points are:

• being able to develop/create a recipe and see/document how it differs (in taste, ingredients, cooking process, etc..) from the previous version/child/change/modification
  • this would be a step by step process. you are essentially running cooking experiments. Some experiments might be failures, some might have you run more experiments on top of existing experiments
    • the reason i mentioned comments/rating earlier was so for each experiment you could take notes. What happened; is it spicier, were the eggs cooked too long, is it missing something, did the taster not like it, etc...
• publish alternative versions of a recipe (these could be considered equal to the original/parent recipe)

What I would definitively vote for would be not to allow crazy stull like merging, rebasing and the like. It is too technical and a tree-like structure is way easier to handle than a graph.

definitely not needed

As @christianlupus mentioned a tree-like structure: Is the requirement to support a tree of versions, such that one can have multiple branches of recipes developing in different directions which at some point may even become a new recipe of their own?

Well the goal is to support the development & modification of recipes (both new and existing recipes). I think a tree of in-progress versions/branches makes sense.

Examples:
Imagine you have a child1 who things your recipe1 is too spicy so you create a modification1, child1 then complains new version is too sweet, so you create modification1+modification2, process keeps going until child1 is happy. You are finally left with recipe1a that child1 likes, this process might take weeks or months. Child2 thinks recipe1 is not spicy enough. You create modification3, child2 still wants more spice so you create modification4. Finally you get recipe1b.

Imagine you don't have all the ingredients for recipe2. You decide to do modification1 which subs potatoes for beets. You note the result (its terrible). You decide recipe2a will never exist. Leaving recipe2+modification1 in history for future reference should you ever try to make this mistake again.

Imagine the serving size for recipe3 (a cake) is too large. You decide to do modification1 which halves all ingredients. You make notes on the result which say icing was not sweet enough. you make modification1+modification2. You continue this process until happy and have a new recipe3a.

Imagine you are a hungry, hungover, college student but do not have the ingredients for any existing recipes. You decide to take whatever you have and create some crazy recipe0.4. It's terrible. You add modification1 (cook the eggs instead of eating raw), its slightly better. Next time you are hungover you use recipe0.4+modification1 but add modification2. It's perfect. You finalize this as recipe4

Should any saved change create a new version or only if I actively create a “tagged recipe”?

Thats what I was thinking. You probably want to separate the process of developing/modifying a recipe from recipes_versions that are ready for use.

Maybe the title of this request was inaccurate and should have said something: Support the development of new and alternative recipes. I feel like i described the original problem "Is your feature request related to a problem? Please describe" somewhat accurately but the original solution not so much.

[christianlupus]

I realize this would be a separate feature request. I already saw that #323 exists and was just trying to figure out how the rating feature might work/integrate with versioning feature. I originally assumed the rating feature would include a text/comment option but reviewing https://github.com/nextcloud/cookbook/pull/342/commits commit messages this seems like it is not the case. I'll raise that as a separate request should it become necessary.

In fact, our plan for #323/#342 was to use the rating field inside the recipe JSON file. That would mean that any commits/version would inherit the comments/ratings from its parent (recursively).

I see two options here to be conforming:

• Remove all comments for each new version. So each version starts with no comments at all.
• Keep the comments on the versions separate from the recipe.json. That way we achieve comments on versions not on recipes.
  This can be implemented during the work for the versioning system.

[christianlupus]

Should any saved change create a new version or only if I actively create a “tagged recipe”?

Thats what I was thinking. You probably want to separate the process of developing/modifying a recipe from recipes_versions that are ready for use.

We might add an option per user that defines the auto-commit feature. The drawback is that the commit might not get a valid description if committed automatically.

[seyfeb]

Should any saved change create a new version or only if I actively create a “tagged recipe”?

Thats what I was thinking. You probably want to separate the process of developing/modifying a recipe from recipes_versions that are ready for use.

We might add an option per user that defines the auto-commit feature. The drawback is that the commit might not get a valid description if committed automatically.

I was just wondering if it might become problematic (used disk space, difficult to display the version history in a way that helps the user keep an overview) if any small cosmetic changes (fixed typos or the like) create new versions. Especially if there is no commit message.

[jessechahal]

I see two options here to be conforming:

• Remove all comments for each new version. So each version starts with no comments at all.
• Keep the comments on the versions separate from the recipe.json. That way we achieve comments on versions not on recipes.

I think for tagged/finalized versions of a recipe removing all previous comments makes sense. For in-development recipes not sure what is the better option. It might depend on if other users are allowed to comment or not.

I was just wondering if it might become problematic (used disk space, difficult to display the version history in a way that helps the user keep an overview) if any small cosmetic changes (fixed typos or the like) create new versions. Especially if there is no commit message.

Honestly I'm not too sure what the UI would look like at this point (on desktop/browser or mobile). I was mostly trying to explain the problem i was trying to solve and relate/compare it to existing software (git). In regards to no-commit msg/note if that ends up being a problem why not just have a default msg?

[christianlupus]

I think for tagged/finalized versions of a recipe removing all previous comments makes sense. For in-development recipes not sure what is the better option. It might depend on if other users are allowed to comment or not.

It is either or the other. Currently we are planning on storing the comments on a per-commit basis. This allows them to be persistent. For in-development recipes this will not cause any sort of trouble.

The issue with a default message is that it might be hard for the user to distinguish the commits. Most of the commits are then simply with the message Auto-commit from date., which is not too involved.

[sdorre]

Nextcloud support natively a simple file revision. Isn't it already want you want ?
https://docs.nextcloud.com/server/stable/user_manual/en/files/version_control.html

[christianlupus]

@sdorre This is not really what we are after. First, there is an automatic aging in the files app. This in contrast to the wish to have a certain set of fixed variants. Additionally, the versioning feature is a feature of the files app. I have not found anything related to it in the API reference.

[meichthys]

@christianlupus I'm not sure if it's what you're looking for, but a DAV endpoint has been added here: nextcloud/server#9353 and the Android app uses it here: nextcloud/android#2685

[christianlupus]

We are not using the WebDAV but use the files in the server part of the app directly. So, we need to handle this separately.