The blender manual is one of the most frequently visited pages. IMO it’s worth it to invest a bit more resources to keep it up-to-date.
Currently, the process for updating the manual is very loose. Essentially, everyone is expected to do their best updating it when changes land. Unfortunately, the reality is that the manual is always a bit out of date and sometimes even completely wrong.
A PR that introduces a change that needs documentation is created.
The PR is tagged (e.g. with a tag “Needs Documentation” of some sort). This could be a “yes/no” checkbox when the PR is created (mandatory?) or the tag is manually added afterwards.
When the PR is merged, an issue on the manual repo is automatically created (and assigned to the PR author?). This would link to the PR/commit for reference. It could also be part of the milestone for the next Blender release.
The issue is closed when a PR that updates the manual is merged.
This should help in the following ways:
It becomes much clearer what the missing changes of the documentation of the next Blender version are. It essentially becomes an automated process.
Developers have an easy overview of changes that they made that need documentation. They need to do very little work to get this overview.
Developers get notifications that their change requires attention in the manual.
Contributions to the manual can become easier: there are tasks that link to the code changes, a PR can be created to close the task, the author of the code changes can review the PR, etc.
Hopefully this solidifies the idea that a change of behavior in Blender introduces a “bug” in the manual.
Having more attention to the manual and helping more of a shared responsibility is surely something we need to have.
While there are some points the proposal solves, there are quite some points that are not clear to me:
We have a lot of PRs that do not need any documentation. So mandating the “Needs Documentation” is not something that would work well in practice.
Not sure why we need a checkbox. I would really prefer us staying as close to the Gitea upstream as possible. All such customizations have a huge cost to maintain. Besides, you can add a label from the PR creation form.
Assigning the documentation task to the PR author is not always correct. We have community contributions, and often it is more practical to take care of the documentation by someone in the module instead.
That being said, having some more automated way to track things is definitely better than the current situation. But feels that maybe it might be someone less “convoluted” of a process. And, maybe, also question of building a culture for the module owners to ensure the work is documented in the manual (just similarly to the release notes).
P.S. One of the more intrusive but potentially way less complicated to track approach would be to merge manual to the blender repository. Maybe even with the developer docs. This way we just would not accept any new feature if it needs a release note or a manual, without going into logistics of dealing with 3 repositories. Maybe also something to consider.
My involvement over the years has been far more on the fringes than in the trenches, but what this bit looks like to me is that, functionally, the current default is “Doesn’t Need Manual Documentation/Update”. I’m sure it’s true that “We have a lot of PRs that do not need any documentation,” but as the above mentioned conversation between filedescriptor, pablovazquez, julianeisel, and fsiddi shows, “we have a lot of PRs that need documentation/updating in the manual” is also true. True enough that “Needs Documentation” should be the default that needs to be turned off if not, instead of the other way around? Or something else where, when the PR is created, “Will this need Blender Manual Documentation/Update Y/N?” is made part of the process?
The proposal isn’t to add this tag by default but rather to either add it manually or to require to choose between “no/yes” on the PR submission form when asked “does this need changes to the manual?”. EDIT: I clarified this in the original post.
Right, a first step could be what I suggested which is to just have a tag that people can add.
Sure, I think it’s good to at least assign it by default to the PR author since that should most often be the person responsible. But tasks can be reassigned. Not a big deal.
I don’t think PRs need to manually tagged. We can do it automatically based on commits whose messages do not start with Fix, Refactor, Cleanup or Merge. I imagine this is already how @Blendify generates the list? There will be false positives, but that’s better than people forgetting to add tags.
I’d love a workflow where documentation can be included in the same pull request. But also not sure how practical it really is to merge the manual repo.
it is true that manual needs updates etc, but if you look at the first few pages of the PRs it is only a handful of them require a manual update. There are a lot of fixes and cleanups. So to me having such label by default is not really helpful.
A middle-ground alternative could be to not approve PRs that require a Manual update unless they have an Issue or a PR already open in the Manual repo.
Of course, something automatic makes it impossible to forget, but it might not be strictly necessary.
Merging the manual repo into the main one may be nice for devs, but maybe not so much for artists contributing to the manual?
The thing with this approach is that it is very easy to overlook the presense of a label (people overlook lack of CI/CD green light, keeping track of labels is much more likely to fall through the cracks). This will lead to tasks created somewhere else, assigned to people, potentially confusing them. So to me it is not undeniably better than forgetting a tag. It could become noisy, requiring someone to cleanup those automatically created tasks.
I was imaging there not to be a label at all, it would be based only on commits. When the issue is created, we can automatically add a good description explaining why it was created, and make sure the assignee gets a notification/email.
I don’t think that would be confusing, but it could be considered annoying. Arguably it would be a good reminder for both core developers and other contributors.
Bypassing the label thing does sound like a simplification!
I guess the main thing I am not fully convinced is the part that the task will be assigned to the PR author. It could create confusion with external contributors, or become annoying to hunt false positives down. Gitea does allow having multiple people assigned, so maybe we just assign both author and the person who landed the PR?
Btw, the manual repo is only 250 meg, so not too bad if we move it to Blender repo?
The main downside would be the mixed history (although not sure how many commits are happening to the manual).
P.S. One of the more intrusive but potentially way less complicated to track approach would be to merge manual to the blender repository. Maybe even with the developer docs. This way we just would not accept any new feature if it needs a release note or a manual, without going into logistics of dealing with 3 repositories. Maybe also something to consider.
I think another downside of mixing the repos is more restrictive write access for the manual, unless there’s a way to configure on gitea which users / groups have the ability to commit to certain directories? I think it may present a bigger hurdle for getting new contributors to the manual too since it implies that they’ll need to pull the entire main repo instead of just the manual.
Regarding the specifics of the process, could we use Gitea’s PR templates here? It wouldn’t require us to make changes that diverge from upstream and I think it would be a good way to incorporate things that are already part of the developer docs that we want to see in PRs anyways. In other (GIthub-based) projects I’ve contributed to, I’ve seen a list of questions that are populated in markdown when creating a PR that pose this and other questions (e.g. “What testing was done / is needed?”, “What documentation needs to be updated?”)
Of course this isn’t foolproof and people can delete the fields, but IMO it does help more directly instill the culture of thinking about these topics if it’s standardized and mentioned in general.