Structure for Release Notes

Documentation
1

The Problem

Every time I work on the release notes, I notice how each release is organized differently.

Before 4.0 the release notes were divided mainly by modules, which could easily lead to confusion:

  • “Nodes & Physics” - Would this include Geometry Nodes, Compositor, Texture Nodes?
  • “VFX & Video” would contain Sequencer and Compositor but they are not related at all.
  • Sculpt, Paint, Texture – Does Grease Pencil belong here? or Animation?

Proposal

I’d like to propose a structure that:

  • It’s easy for users to find what’s new, regardless of the module.
  • Surfaces important areas and workflows (Geometry Nodes, Grease Pencil, etc)
  • Serves as reference guideline for new contributors, especially now that everyone can edit release notes.

At the moment the list is flat with top-level entries only. Another approach could be to group sections into sub-sections.

Below is the full list of sections, they may seem many but we rarely have updates in every area. Sections should only be added when needed.

3D Viewport

  • 3D Viewport - viewport.md
    • Workbench, overlays.
  • VR/XR - xr.md

Animation

  • Animation - animation.md
    • All animation editors.
  • Rigging - rigging.md

Assets - assets.md

  • Asset Browser
  • Essential Assets Bundle

Core

  • Core - core.md
    • Undo, CLI, .blend file, data-blocks, library updates.
  • Compatibility - compatibility.md
    • Deprecated libraries, devices, OS.

Grease Pencil

  • Grease Pencil - grease_pencil.md

I/O & Pipeline

  • Library Overrides - library_overrides.md
  • Import/Export - import_export.md
    • Including add-ons that ship with Blender (e.g. FBX, glTF)

Modeling

  • Modeling (& UV)
    • modeling.md
    • Mention “& UV” when there are changes in that area.
    • Includes modifiers.
  • Geometry Nodes
    • geometry_nodes.md
  • Sculpting
    • sculpting.md
    • Mesh sculpting.

Rendering

  • Color Management - color_management.md
  • Compositor - compositor.md
  • Cycles - cycles.md
  • EEVEE - eevee.md
  • Painting & Textures - textures.md
    • Vertex Paint, Texture Paint, brushes.
  • Rendering - rendering.md
    • Lights.
    • Shader changes that cover all engines.
  • Hydra

Scripting

  • Python API - python.md
    • API updates.
    • Breaking changes.

User Interface

  • User Interface - user_interface.md
    • Default theme, changes to fonts, icons.
  • Keymap - keymap.md
  • Outliner - outliner.md

VFX & Video

  • Motion Tracking - motion_tracking.md
    • Movie Clip editor, tracking nodes.
  • Physics (& Simulation?) - physics.md
    • Mantaflow, rigid bodies, dynamic paint, etc.
  • Sequencer - sequencer.md

Extensions

  • Add-ons - add_ons.md
    • Includes changes to add-ons that ship with Blender, except I/O.
  • Extensions Platform - extensions.md

Corrective Releases

  • Corrective Releases - corrective_releases.md

Open Questions

  1. Where would Text editing go? Modeling, UI, Viewport?
  2. Where should curve sculpting go?
  3. Ocean modifier updates is technically not physics, but not modeling either.

I’m probably missing a lot here, would appreciate feedback so we can make updating release notes easier and more organized.

12 Likes
2

Hola, hard to categorize geometry nodes, sometimes its modelling, sometimes its physics…

Text Editing is probably modelling, special but would fit there…

Ocean modifier is just a modifier as the others? I would not put it anywhere else since its by law a modifier.

3

I used to re-organize pages as needed during development, but then at some point there was an agreement to have a fixed organization by module. Which indeed is not very clear for users.

What I did or 4.0 and 4.1 release notes is that once we go to bcon3 (bug-fixing only), I reorganized pages to be better balanced and describe the contents. With the idea that this should not bother those who prefer to have release notes organized by module and not worry about where to put information, since all features are in at that point.

I’m fine with this list as a guideline, hopefully it is clear enough for developers where to put things and we can avoid the module pages from the start.

I do think it makes sense to have some flexibility every release to merge or split pages as needed. For example Color Management and Hydra might have deserved their own pages in 4.0, but for 4.1 it seems reasonable to keep it all on Rendering since there is not that much content. Or for example I’ve sometimes moved 3D Viewport, Node Editor and Text Editor changes into the User Interface page if there were only minor changes. I don’t think Outliner always needs its own page if there was only a minor change.

5 Likes
4

The one thing about release notes that is sort of annoying as a user, is the multiple separate pages of everything by module or area.

Certainly those have value, to be sorted, but I always wish there was just a single html page with everything flowing in sequential sections. I just want to read one page, top to bottom.

Thanks for taking the time to look for ways to improve docs. :slight_smile:

6 Likes