[v1.0.0b] [Task] - Improve documentation on 0.5.x migration

What is the problem this task addresses?

There were a few cases in the discord lately where people wanted to migrate from 0.5.x to v1 but had problems with the migration and people have a bit of a hard time helping them, because everyone that is active there hasnt used 0.5 for ages. E.g. it is unclear how you actually correctly create a data export in 0.5, is it the same as a backup? I cant say that I know If v1 is gonna be released I'd expect an even bigger influx of these cases so it shouldnt hurt to be prepared

Proposed/Possible Solution(s)?

Make step 2 in the current migration document a bit less vague. Add specific navigation instructions or maybe some screenshots, so users can be certain that they got the right data, before doing the update

another thing that came up today: some reverse proxies will have default upload limits (e.g. 1mb for nginx) which will cause the migration to silently fail. it probably wouldnt hurt to maybe add some info about that as well, so users are at least mindful of it

Oh man I'd love to hear something on this one.

I'm on 0.5.6 right now and there IS NO EXPORT.

There IS NO BACKUP.

It's NOT THERE. I promise it isn't, I've looked at every page ten times, using two different admin accounts. I spent the last twenty minutes looking.

There's also a Backups folder in the filesystem, which hasn't been updated since Feb 6..it's June 24 now. So, that's clearly not working either.

Is this a known issue? How can I get an export most easily? My goal is to move away from Mealie, if I'm honest. I don't like the idea of sitting on an old version, even if it works.

I love Mealie but there's no Public recipe support and that's 100% not optional for us, so I'm abandoning Mealie as soon as I can. Tandoor would be nice, but it doesn't import from this version of Mealie properly. I have a feeling I'd have better luck appealing Tandoor to fix the import than getting Mealie's devs to address this.

Oh man I'd love to hear something on this one.

I'm on 0.5.6 right now and there IS NO EXPORT.

There IS NO BACKUP.

It's NOT THERE. I promise it isn't, I've looked at every page ten times, using two different admin accounts. I spent the last twenty minutes looking.

Is this a known issue? How can I get an export most easily? My goal is to move away from Mealie, if I'm honest. I don't like the idea of sitting on an old version, even if it works.

You can either upgrade to the latest beta or wait for the RC when I have more time to work on it later this year, or switch to another application.

I love Mealie but there's no Public recipe support and that's 100% not optional for us, so I'm abandoning Mealie as soon as I can. Tandoor would be nice, but it doesn't import from this version of Mealie properly. I have a feeling I'd have better luck appealing Tandoor to fix the import than getting Mealie's devs to address this.

Getting Mealie devs to address what? Public Recipe support is on the roadmap and there's already support for sharing individual recipes in the latest beta.

https://github.com/hay-kot/mealie/issues/1326

If you want to see this feature sooner, you can pay a developer to work on it, or work on it yourself.

WOW I have no idea how I missed that. What an oversight. I do feel foolish.

To be fair though, I was trying to find it using your actual provided migrating documentation, which is -- and this is WILD -- in the entirity of the page and its contents, nowhere near as good as that single screenshot you just provided.

Here, check this out;

No information on where anything is.
The "in the admin section" note is SUPER vague, also there is no admin section. You want users to find the Dashboard while logged in as the Admin USER, but an "admin section" makes me think "Settings" which is completely different, and also does not exist while logged in as a non-Admin user, and the requirement to be logged in as admin is not even vaguely hinted at.
Didn't use any similar/same names (Export? There's no export feature/wording anywhere on the entire app!)
"Be sure to include recipes when performing the export." You have to do a Custom Backup, -and- switch from "Full backup" to "Partial backup" to even see that you can exclude anything, so that line made me feel like I did something specifically wrong when neither of my "Create" (I assume that's short for "Full Backup"?) and "Custom" backups gave any options resembling what I was instructed to perform, until I went out of my way to do things I was not instructed to do.

Further, I muddled my way to the "Backup and Restoring" section of the provided documentation.

Trouble RIGHT AWAY. "Navigate to /admin/backups/ to" -- I'm just gonna go out on a limb and assume that this refers only to Mealie v1 and not to pre-v1, because on my instance that leads to a giant 404. I ALSO found that while flailing about trying to figure out how to get to the Backup section.
There's a Tip right below the first paragraph under the "Backup and Restoring" header, and a Warning further below which addresses "prior to beta-v5" but nothing addressing pre-v1, which leads users to assume there is no known issue/difference in this section between v1 and pre-v1 except pre beta-v5. It's misleading and inaccurate.

"Click this button" -- which button? There's no button image or description anywhere on the page.
"This can be done through the web portal" -- completely not helpful in any way, except to let you know that you're definitely missing something if you don't know where it is already.
"on the lower left hand corner of the backups data table" Really? It's on the top right. (Also top right in the screenshot you uploaded.)

Also super neat -- I'm commenting on a thread that complains about how vague this documentation is, so I'm clearly not alone on it. Maybe don't just ignore me as some asshole and actually spend a minute with what I'm saying. I may not be going out of my way to be kind, but I'm not wrong in my analysis and I am sincere on wanting improvement for the project as a whole, not merely myself.

You can either upgrade to the latest beta or wait for the RC when I have more time to work on it later this year, or switch to another application.

Actually I knew that (especially the whole "you have no choice I'm the dev" vibe) but I really couldn't migrate to another app or upgrade because I couldn't find the Backup information, explicitly because the guide is both poorly explained and inaccurately worded. So, I explicitly could not upgrade or switch to another application without losing my data, which is what drove me to post about being unable to Backup so I could switch or upgrade due to poor documentation, on an open Issue about the poor Migration documentation. Like, even if I had figured it out, I really still would've been justified to come here and say "Agreed, this documentation is awful, please do anything about it."

Mealie has been amazing, and I apologize for being snippy. I really wish I could keep using it, but my choices are A) Keep using an outdated, unpatched, unmaintained version. Optionally hope that the roadmap is followed, completed, and never modified adversely. B) Update and lose absolute dealbreaking features. Optionally see above. C) Migrate to another app.

Getting Mealie devs to address what?

I have a feeling I'd have better luck appealing [...] than getting Mealie's devs to address this.

That was unfair and an unjust jab because I was super frustrated from spending so long reading -all- of the available documentation and getting nowhere. I apologize, it was flat wrong of me to say.

tl;dr:

Getting Mealie devs to address what?

THE POOR DOCUMENTATION.

tl;dr:

Getting Mealie devs to address what?

THE POOR DOCUMENTATION.

You do realize you're commenting on a task that addresses needing to improve the migration documentation, right?

A few things.

The https://nightly.mealie.io documentation only refers to the nightly tagged release (or beta releases, whatever you want to call it). The actual v0.5.x documentation is at this site https://hay-kot.github.io/mealie/. So you're right in that it won't apply to the v0.5.x and may be confusing. I can understand making this mistake.

I don't disagree that the documentation for migrating is poor - that's why this issue exists. There are lots of places where the documentation could improve.

Also super neat -- I'm commenting on a thread that complains about how vague this documentation is, so I'm clearly not alone on it. Maybe don't just ignore me as some asshole and actually spend a minute with what I'm saying. I may not be going out of my way to be kind, but I'm not wrong in my analysis and I am sincere on wanting improvement for the project as a whole, not merely myself.

I went out of my way to spin up and instance of v0.5.x on my machine to get you a screen shot to help you out. I don't really feel like it's fair to say I'm just ignoring you as some asshole.

"you have no choice I'm the dev"

You have literally all the choices. It's free and open source software that you can do with what you want under it's license. I don't have time to fix this right now. That's not stopping you or anyone else from taking the time to do it. I make very little money from this project on donations which a fair amount of it goes to maintaining the demo site. This is not a job for me or anyone else. It's a side-project that I work on when I can.

Me and other maintain this for free in our spare time. There is no warranty, there is no promised support. We don't owe you or anyone else anything.

@hay-kot - I'm gonna address the most important bits first;

I went out of my way to spin up and instance of v0.5.x on my machine to get you a screen shot to help you out. I don't really feel like it's fair to say I'm just ignoring you as some asshole.

You're damn right. I'm sorry, but the wording came across initially as dismissive and I reacted poorly. I very much appreciate you spinning up a fresh instance for me. I certainly no longer have that impression and I'm sorry for accusing you of it. I don't mean to sound ungrateful. I very much appreciate very ounce of effort everyone involved has put in.

The https://nightly.mealie.io documentation only refers to the nightly tagged release (or beta releases, whatever you want to call it). The actual v0.5.x documentation is at this site https://hay-kot.github.io/mealie/. So you're right in that it won't apply to the v0.5.x and may be confusing. I can understand making this mistake.

Of course it's confusing. Nothing explains that anywhere except now this issue and maybe a few other closed ones I assume. I didn't examine the URL; I didn't realize I was at the nightly docs site. Aside from the URL, there's no way to know that in the first place. I clicked "Explore the docs" from the Github page. I also clicked the "Docs" link from the main Mealie site, and it went to the same nightly docs site.

If it doesn't apply to the pre-v1 Mealie instance, don't link there from literally everywhere that has a reference link of Docs, or make it clear that it's v1+ only.

As for 'fixing' things, you've taken more time to address me bitching about this documentation than it would take to fix the documentation. I understand that code takes time, but even an hour to fix up a dozen paragraphs would pretty much solve it. I'll even do it myself -- I promise to be well behaved, or submit any changes for review. As I said, I do have a sincere interest in improving the project.

I love the Mealie project and it -really- annoyed me to feel like all of my hard work (and family members, friends, etc) entering data was just trapped there, so I stressed out. I'm not justifying my actions; I was wrong, I'm just trying to help understand why I was so stressed out.

@michael-genson

You do realize you're commenting on a task that addresses needing to improve the migration documentation, right?

I do. I didn't feel like I had to be snarky and overexplain that before. You do realize that I'm commenting on getting the devs to actually address it, right? The process will never change; that version is not being updated, thus the actual need for addressing the migration documentation. It's a one-time task which is causing active issues to those trying to help others within the Discord community, if I understand correctly. Surprisingly, I read that in the first message. Don't play like I'm not paying attention.

I feel like a lot of people use https://hay-kot.github.io/mealie/ when they'd rather use the new version. Except in this instance because the biggest difference is the public recipe view. I personally also started on 0.5 because it is what Google seems to suggest first and I only knew about 1.0.0 (and switched) because I wanted to file a bug report for 0.5 and github asked me what version I was spinning...

I don't know what percentage of the users this encompasses, but having a banner/warning on https://hay-kot.github.io/mealie/ about the difference and that 1.0.0 is better (and better supported both in code and in help) if you don't need public recipes, might help?

Do you have some points where to edit the 0.5 site? Or opinions about trying to get users to nightly.mealie as quickly as possible?

YOu keep referring to 'the devs' but this is an open source project. If you decided to fix it yourself, you'd be part of those devs too. Anyone who wants to is. I get the frustration with inactivity from main maintainers, I've had that before, but only because PRs might be open for months without any comment. That is frustrating because you really can't do much about it then. Mealie gets updates quite frequently and hay-kot actively helps with reviewing and merging new features if they are useful. What only stops a fix for something is someone wanting to put free time into it. And documentation, especially for a very outdated version, is unfortunately something quite boring (and not that easy) to do. So it won't get high on people's list when they decide they want to make mealie better.

Of you'd join the discord and look at it for the last few months you'd see how much effort is put in both increasing the features of mealie and helping anyone who has questions, even when often the problem doesn't even lie with mealie. you'd probably also have a solution to your problem (if you'd asked nicely) and would have the knowledge then go fix this documentation yourself.

Getting angry and snarky at people who put their free time in a project is really not the way to fix this problem..

I don't mean to sound like I'm lecturing or throwing a tanrum or anything. I'm calm. I came in hot as hell and I apologize for that. I need a blocker on my PC so I can't post while I'm still irate. I'm rambling and long winded but that's because I want to be clear on my thoughts and intents.

You keep referring to 'the devs' but this is an open source project. If you decided to fix it yourself, you'd be part of those devs too. Anyone who wants to is.

You must've missed the part in my long-winded ramble where I offered to do the work. I'm asking for changes to documentation, ~~and to my knowledge that's not public-edit access. I don't expect to be trusted with the keys,~~ (I actually just found where the docs are in the repo because while typing that I realized I never looked so I'll try to set up an environment and make a PR. ) but ...

Do you have some points where to edit the 0.5 site? Or opinions about trying to get users to nightly.mealie as quickly as possible?

... that's what all of the things I said were. "This is incorrect/unhelpful/inaccurate/misleading, it's actually this." I wasn't just trying to dogpile on the point, it really was intended as a list of specific notes on specific issues -- I didn't go into corrections because most of them felt clear once you identify the issue and I felt that would be perceived as even more hostile.

If you'd join the discord [...] if you'd asked nicely [...] you'd probably also have a solution to your problem [ ... ]

This is SPECIFICALLY why I didn't join the Discord though. I don't want anyone to need to have to go to a realtime public place with no easily managed history relying on the presence of active, communicative, experienced, patient people to one-on-one communicate instructions with those who may be bad at comminucating in public because they fly off the handle with their temper (ahem) or speak a different language poorly but read or translate well, etc etc etc.

Even the most well-intended person who communicates poorly makes that transaction difficult, from either side. How many of us dread calling tech support because we're gonna wind up talking to someone who doesn't know what they're doing, can't answer a simple question, etc? That aside, these docs would've prevented EVERYONE from having to deal with the likes of myself. I'd imagine I'm not the first, last, or best of them.

Docs are docs, they don't care how pissed you are; if they do their job you don't get your pissed on everyone else's groove. Actively requiring folks to discard documentation and move to a chat room is just BAD right?

Where do the most experienced users go? Directly to the Documentation.

I want the documentation fixed. For Everyone. I know the knowledge is out there, I know there's an active community and progress being made all the time. The procedure which needs to be written will never change, so there's never a point where it's going to be easier. It'll get harder as fewer and fewer people remember. It gives the project an awful vibe. Sure it grows less relevant but this issue is why I didn't update in February or May or whichever, and it's still exactly the same, and it soured me entirely on Mealie twice now.

It affects users wishing to upgrade or migrate as badly as a critical migration bug between versions. It's acknowledged by this community. It needs to get done. It makes Mealie better by not having a broken transition point that refuses to be addressed unless you can find someone in the chat group willing to walk you through the common knowledge for the twentieth time. I don't get the resistance. "Nobody wants to do this once in detail; just go have someone do it again realtime." That's SO wasteful of everyone's effort.

AND -- it wasn't in the TL;DR twice now, so I'll say it a third time -- I offered to do it. I really will, and I'lll do what I consider to be a damn good job. At the time I didn't realize I had the access. I can't guarantee I'll cover anything else, but I'll definitely try to take time to cover the migration page if I can get the environment up.

Actually I have low confidence on my ability to do this correctly just cloning and prodding.

What do I clone/fork (repo and branch specifically) and where within that repo's paths do I make edits for the pre-v1 documentation site?

What do I clone/fork (repo and branch specifically) and where within that repo's paths do I make edits for the v1+ documentation site?

Are there other locations I should examine while attempting to make a pass at documentation for either branch of the project?

Is there any other significant branch/breaking version change point?

mealie-recipes / mealie

[v1.0.0b] [Task] - Improve documentation on 0.5.x migration #2223

What is the problem this task addresses?

Proposed/Possible Solution(s)?