Page MenuHome

Fix T53286: Upgrade information is missing in manual
ClosedPublic

Authored by Alaska (Alaska) on Mon, May 11, 2:44 AM.

Diff Detail

Repository
rBM Blender Manual

Event Timeline

There are a very large number of changes, so older changes are hidden. Show Older Changes
Alaska (Alaska) added a comment.EditedMon, May 11, 11:33 AM

@Yevgeny Makarov (jenkm) and @Brecht Van Lommel (brecht) Do you believe this should be added to troubleshooting instead? If I add it to the troubleshooting section, I will also include steps on how to fix the issue.

Removed note about compatibility issues when loading defaults from previous versions of Blender.

Waiting for a response from reviewers on whether or not this should be re-added to a troubleshooting page or left out of the manual entirely.

Alaska (Alaska) marked an inline comment as done.

Updated the expanse of the fix to cover the entire task.

Definitely not complete and I'm willing to accept feedback and information from other users.

I also feel a image should be added to "/getting_started/configuration/defaults", if others believe this is useful, just say so and I will commit it separately.

manual/getting_started/installing/linux.rst
74

Need input from others. Are updates automatically installed and maintained by the package manager?

manual/getting_started/installing/macos.rst
46

Need input from someone with experience with MacOS.

52

Need input from someone with experience with MacOS.

manual/getting_started/installing/windows.rst
49

Need input from someone with experience with the MSI.

you have a typo "verions"

@Brecht Van Lommel (brecht) I currently do not know of any cases of this, but have based this on the comment at T53286#471095

Ok, please leave it out then. Incompatible (add-on) preferences after upgrading Blender is not a typical problem.

you have a typo "verions"

Didn't notice that. Fixed in the up-coming diff. It's getting late where I am. So I may go to sleep and continue work on this in the morning.

Fix spelling and integrate information from @Yevgeny Makarov (jenkm)

@Sybren A. Stüvel (sybren) You talked about linking a explanation about how Blender stores its settings. Are you able to give me pointers in where it should be linked? I'm thinking it should be linked in "/getting_started/configuration/defaults" with something along the lines of:

Load Previous Version Settings
Copies preferences and startup files from the previous version of Blender then loads them.
Settings need to be imported from previous versions because each version of Blender stores their configuration files in separate folders. Refer to the Blender directory layout for the location of Blenders configuration.

Would love to hear your feedback on whether this is too much, should go somewhere else, needs more information, etc.

@Alaska (Alaska) there are more changes in my macos.rst file above, just use the entire content. (there is no longer a zip version for Mac)

Would love to hear your feedback on whether this is too much, should go somewhere else, needs more information, etc.

I like the text. Especially in a "Getting Started" section we can't assume readers know how Blender works. Having links to where to find more information is essential then. I also think you picked the right location for that text.

Only two minor nags:

stores their configuration

Blender is singular, so I would say "stores its configuration".

Blender directory layout

Since it's a section in the manual, I'd capitalise this into "Blender's Directory Layout". However, given that that is already the section title, that's probably automatically done when adding the link to the manual.

manual/getting_started/installing/linux.rst
74

That depends on the distribution. For example, Mint Linux is still using Blender 2.79.

82

It might be nice to explain that this way multiple versions can be installed side-by-side. Maybe that's already in the linked section, though, in which case it doesn't have to be mentioned here.

manual/getting_started/installing/linux.rst
74

I would encourage users to check their package manager, warning that it may be out of date, but then recommend to install from blender.org as the latest version is always available there.

manual/getting_started/installing/macos.rst
52

Using the DMG is the only to install blender on macOS

manual/getting_started/installing/windows.rst
49

Simply download and execute the installer. You can install multiple versions alongside others. Older versions have to be uninstalled after the fact through windows.

Alaska (Alaska) marked 3 inline comments as done.Tue, May 12, 2:22 AM

@Alaska (Alaska) there are more changes in my macos.rst file above, just use the entire content. (there is no longer a zip version for Mac)

Sorry. It was around 2am when I looked at it.


Only two minor nags:

I hope to have addressed them in the next diff.


@Aaron Carlisle (Blendify)

I would encourage users to check their package manager, warning that it may be out of date, but then recommend to install from blender.org as the latest version is always available there.

The out of date part is already covered on the same page with:

Be aware, though, that the package may be outdated compared to the latest official release, or not include some features of Blender. For example, some distributions do not build Blender with CUDA support, for licensing reasons.

I actually found out about that when re-reading over everything again today. Should I repeat something like this in the "updating" section or leave it?

I would also like to hear your feedback on the MSI section. I tried setting up a Windows Virtual Machine to test the MSI system out, but couldn't get it to work (the virtual machine, not the installer).

Update general information.

manual/getting_started/installing/windows.rst
46

Would say Updating from MSI or Updating from Installer to be consistent.

52–53

It does not matter if it is uninstalled before or after. I would say To remove a previously installed version of Blender, use Windows settings or control panel to uninstall the desired version

Alaska (Alaska) marked 3 inline comments as done.Tue, May 12, 2:41 AM

@Aaron Carlisle (Blendify) I hope to have address your comments with the new diff.

Alaska (Alaska) marked 2 inline comments as done.Tue, May 12, 2:43 AM
Alaska (Alaska) added a comment.EditedTue, May 12, 10:37 AM

Quick question for everyone. Are you experiencing this issue?

#1213: Deadlock found when trying to get lock; try restarting transaction

It only seems to occur when I load this diff and its been happening throughout the entirety of today. I've tried logging out and logging back in to the developer.blender.org website. Terminating all instances of my account on developer.blender.org. Closing my browser and re-opening, clearing cookies, rebooting my computer, using a different device. Just can't seem to get it to work. It's an issue I'm concerned about because it seems to be stopping the loading of /getting_started/configuration/defaults and /getting_started/installing/linux and if the same happens to anyone else, then this diff can't be reviewed.

Yes, I also get that error.

Looks good to me however, I would like to hear from @Sybren A. Stüvel (sybren) before committing.

This revision is now accepted and ready to land.Wed, May 13, 1:11 AM

Looks good to me however, I would like to hear from @Sybren A. Stüvel (sybren) before committing.

What do you think of my suggestion.

https://developer.blender.org/D7684?id=24612#inline-62177

manual/getting_started/configuration/defaults.rst
55

I would word it this way

Loads preferences and startup files from the previous version of Blender.

Alaska (Alaska) marked an inline comment as done.Wed, May 13, 2:30 AM

@Eitan (EitanSomething), @Sybren A. Stüvel (sybren) said:

This is not entirely correct. The button copies the settings from the previous to the current version of Blender, then loads those.

In response to my original diff which read:

Loads preferences and startup files from the previous version of Blender.

Hence why I changed it to what's included now. I will mark your comment as "Done" but will change the diff if @Aaron Carlisle (Blendify) or @Sybren A. Stüvel (sybren) ask me too.

Okay that makes sense

manual/getting_started/installing/linux.rst
34–35

I wouldn't mention any purposes here. Multiple versions of Blender can be installed regardless of the user's purpose.

72

This is not specific for Linux, so it shouldn't be in the Linux subsection. I notice that it's mentioned with every OS, though. Why not mention it in an "Updating Blender" section, and have the platform-specifics as subsections?

After removing this text, though, you'd end up with a textless section, which is bad style. Probably a little introduction is in place, like "On Linux there are various ways to obtain and install Blender. This section covers the most common approaches."

77

"The package manager" is ambiguous. I would also just write a few more lines of text here, instead of trying to get as much info as possible into one sentence. How is this?

Many Linux distributions have packages for Blender available, which can be installed using the distribution's package manager. After installation, Blender can be updated using the same steps as updating any other application.

Given how old packaged Blenders can be, I think it's better to move this subsection further down.

Alaska (Alaska) marked 3 inline comments as done.EditedFri, May 15, 10:40 AM

@Sybren A. Stüvel (sybren)


Given how old packaged Blenders can be, I think it's better to move this subsection further down.

I updated the text as you asked, and shifted the sub-section down. I have also moved the "Install from Package Manager" section down so when a user goes to the "Installing on Linux" page they are greeted with the "installing from blender.org" section first.


This is not specific for Linux, so it shouldn't be in the Linux subsection. I notice that it's mentioned with every OS, though. Why not mention it in an "Updating Blender" section, and have the platform-specifics as subsections?
After removing this text, though, you'd end up with a textless section, which is bad style. Probably a little introduction is in place, like "On Linux there are various ways to obtain and install Blender. This section covers the most common approaches."

I've implemented this into the manual in a way I believe works. But I would love to hear your feedback.

(Added as a note in /getting_started/installing/index)


Also, should I update the "/getting_started/installing/index.rst" page to have the title "Installing and updating Blender" as it now technically covers both sections?

Implement suggestions

Alaska (Alaska) requested review of this revision.Fri, May 15, 10:41 AM

Change wording to better fit the context.

Alaska (Alaska) added a comment.EditedSat, May 16, 8:48 AM

@Aaron Carlisle (Blendify) and @Sybren A. Stüvel (sybren) based on what I've been able to find on developer.blender.org and other sites, it seems the Blender foundation distributes Blender via Steam. Is this true? And if so, should I add a section for it to the manual?

Here's a quick draft I wrote if you wish for me to add it:

Installing from Steam
=====================

Download Steam for your operating system from the `Steam website <https://store.steampowered.com/>`. 
Once installed navigate to the *Store* tab in the Steam client and search for Blender and install it on your system.
Now Blender should be available in the "Library" tab of the Steam client.

A shortcut for Blender can be added to your desktop by navigating to your Steam library, 
:kbd:`RMB` Blender and selecting :menuselection:`Manage --> Add desktop shortcut`.


Updating with Steam
-------------------
When an update for Blender is available, Steam will automatically update Blender for you.

I have a few questions about this assuming you want me to add this.

  1. Should I add this section to each individual page for Windows, MacOS, and Linux, or should I add it as a section in "manual/getting_started/installing/index"?
  2. Should I get rid of the "Updating with Steam" and just integrate it into the "Installing from Steam" section with something like this:
Installing Blender through Steam has the advantage that all available updates are automatically installed by the Steam client.
  1. In "manual/getting_started/installing/index" it says "The procedure for installing a binary, either the latest stable release or a daily build, is the same." Is there a way to install a daily build of Blender through Steam? If not, should I add a note to my description explaining this.
  2. Is there any other feedback you'd like to give?

based on what I've been able to find on developer.blender.org and other sites, it seems the Blender foundation distributes Blender via Steam. Is this true? And if so, should I add a section for it to the manual?

I think adding information about Blender on steam would be a good idea to make it more public that Blender is available on that platform.

Adding to this Blender is also available on the windows store so information should also be added for that. This can be added to the windows page.

Should I add this section to each individual page for Windows, MacOS, and Linux, or should I add it as a section in "manual/getting_started/installing/index"?

I would create a new page manual/getting_started/installing/steam.rst

Should I get rid of the "Updating with Steam" and just integrate it into the "Installing from Steam" section with something like this:

For consistency between other pages, you should keep the section header.

In "manual/getting_started/installing/index" it says "The procedure for installing a binary, either the latest stable release or a daily build, is the same." Is there a way to install a daily build of Blender through Steam? If not, should I add a note to my description explaining this.

There is not a way to install a daily build through Steam; I do not think it is necessary to point that out.

Is there any other feedback you'd like to give?

So far looks good.

@Aaron Carlisle (Blendify) I've added the information describing the process for Steam and the Microsoft store.

You or someone else will need to check over the "Microsoft store" addition in the "Windows" section. I've personally had very little experience with it.

Also, should I add something about how the Microsoft store doesn't automatically update Blender when on a metered connection? Or should I just ignore it?
From the looks of it, Steam auto updates have to be disabled manually and don't respect metered connections so there's nothing to add to this section if you would like me to add something about metered connections.

Alaska (Alaska) updated this revision to Diff 24898.EditedTue, May 19, 6:38 AM

Integrated Steam and Microsoft store information

A couple of small formatting things from me. Unless @Sybren A. Stüvel (sybren) adds anything you can commit.

Also, should I add something about how the Microsoft store doesn't automatically update Blender when on a metered connection? Or should I just ignore it?

This can be ignored, it is overly specific.

manual/getting_started/installing/steam.rst
1–2 ↗(On Diff #24898)

Use Correct title markup

*******************
Installing on Steam
*******************

Similar change needs to be made below also.

manual/getting_started/installing/windows.rst
44

Capitalize store in "Microsoft store"
"Downloading" should be "Installing"

76

Same here

This revision is now accepted and ready to land.Tue, May 19, 7:06 AM
Alaska (Alaska) marked 3 inline comments as done.

Fix formatting

Fix more formatting errors.

Alaska (Alaska) requested review of this revision.Tue, May 19, 7:15 AM

Normally I would suggest leaving the Steam part for another patch. That way you can get things right first (this patch), and then expand what you have by adding new topics (Steam, but also Microsoft Store, and Snap is still not described I think). It's in there now, so I have added a few inline comments.

manual/getting_started/installing/steam.rst
3 ↗(On Diff #24901)

"Installing from Steam" or "Installing via Steam" would be a better title. "Installing on Steam" could imply that you put something on the Steam platform itself.

16 ↗(On Diff #24901)

"is available" → "is available on Steam". There can be a slight delay between publishing the release on the blender.org website, and it being available on Steam. We don't want to promise immediate availability.

manual/getting_started/installing/windows.rst
54

I wouldn't just use a three-letter acronym here, as there are many things named MSI. Either use "MSI File", or even better "Windows Installer File". Referring to files by their extension has the problem that by default Windows Explorer hides extensions. Many users will never see them.

Alaska (Alaska) marked 3 inline comments as done.

Include suggestions by @Sybren A. Stüvel (sybren).

Alaska (Alaska) added a comment.EditedTue, May 19, 10:09 AM

@Sybren A. Stüvel (sybren) I've updated the manual with your suggestions and have hopefully covering your concerns.

I'm still not sure about the way that Steam is now added to the manual. It's not mentioned in the Windows, Linux, or macOS specific pages, so it's not part of any of the platform-specific overviews on how to install & upgrade. Installing from Zip file is listed there, even though it's the same for each platform, but Steam gets a separate page. Furthermore, the Steam page doesn't mention which platforms it's available for.

Alaska (Alaska) added a comment.EditedTue, May 19, 10:51 AM

@Sybren A. Stüvel (sybren)

Installing from Zip file is listed there, even though it's the same for each platform.

Installing from zip is no longer an option for MacOS. It makes sense to me for why it's on the separate pages of Windows and Linux.

As for the other issues you talked about

[Steam]'s not mentioned in the Windows, Linux, or macOS specific pages.

Now that you point it out, it does seem kind of odd. It also seems a bit odd to list Steam (a program), along side Windows, MacOS, and Linux (operating systems) in the /getting_started/installing/index page.
I can think of a few options:

  1. Leave it as I've got it in the diff currently.
  2. Add links to the Windows, Mac, and Linux pages pointing to the Steam page.
  3. Get rid of the Steam page and add the description of installation/updating to the separate Windows, MacOS, and Linux pages.
  4. Remove the Steam page from this diff, iron out what I've added already, commit this diff, then create a new diff where we can discuss the Steam integration into the manual. (What you suggest earlier with:)

Normally I would suggest leaving the Steam part for another patch.

I'll leave the decision up to you and/or @Aaron Carlisle (Blendify)

Let's do the latter, because this diff already adds value to the manual.

Remove the Steam page. To be added in a later patch.

This revision is now accepted and ready to land.Tue, May 19, 1:10 PM