Non-existing branches cause the "pull docs" task to fail entirely

[ScopeyNZ]

If the config references a non-existing branch then you get an error like:

cloning silverstripe/silverstripe-userforms/4
warning: Could not find remote branch 4 to clone.
fatal: Remote branch 4 not found in upstream origin

This breaks the whole task and the site has no content. This should be more error tolerant.

[ScopeyNZ]

We could probably catch this, show no content for that specific part of the docs, and trigger a message through Raygun...

[robbieaverill]

How about we use tags instead? We don't usually exclude docs from distributable packages, so should be OK. It might just mean it takes a little longer to get docs onto the site.

I've also suggested we have one centralised repository for userhelp rather than splitting it across many, but it sounds like people don't like that idea.

[sachajudd]

Having a centralised repo for user help would (I assume) mean that the user help wouldn't be attached to the repos anymore or would need updating in two places which I think would create more work. I also think it would get outdated quite easily in the future if someone wasn't on top of it. If we could find a more cleaner and reliable way like the idea of using tags and document correctly how it works etc I think it could solve the issue.

[robbieaverill]

Having a centralised repo for user help would (I assume) mean that the user help wouldn't be attached to the repos anymore or would need updating in two places which I think would create more work

Yeah to clarify, I'm suggesting we have one single repository for all userhelp, and remove it from individual modules.

I've also suggested we do this for developer documentation.

[sachajudd]

Ah right, that makes more sense 😂 although we don't always support the modules and some community modules have their own user help that we'd in future potentially want to pull in. Wondering how we'd deal with that situation?

[robbieaverill]

I'm not sure I see the value there - you're saying we'd pull in content from third party modules but not support that content? It'd still be presented in a "SilverStripe userhelp" frame, so may as well include support for it if you want to use it

[sachajudd]

Yeah so we could potentially pull content in from third party modules if they contain user help and if we think the majority of users would benefit from them. We want to make it as easy as possible for the devs to make improvements updating user help at the same time as updating dev docs and not rely on us, or be blocked by us updating and merging in changes. Its easier for us to contribute to their repos and they manage and review as they should have the appropriate context. Often we don't have the complete context but we can help to provide a more consistent voice and standard of writing. Unfortunately we don't have the capacity to support all of user help and rely on the open source community to supply it.

[robbieaverill]

I think you will need to be careful if you start bringing in content from third party modules (outside of commercially supported modules) and presenting it under the SilverStripe brand.

Anyway - we digress. I agree that having the content in separate repositories is possibly better from a maintenance perspective, however I think that moving it all into one repository would be better from a documentation perspective. That is to say that the repository would only contain documentation, does not have to be tied to code changes, releases, continuous integration builds (for code), etc. It also doesn't have to be tied to specific versions of the codebase, although you may want it to be. Turning this into a pretty meta discussion - but it's worth considering anyway.

For now I think using tags is a good middle ground. We'll need to do some modification to this codebase to handle this.

[robbieaverill]

Side note: I'm going to be looking into alternatives to docsviewer and self hosted websites (like this one) for SilverStripe's documentation shortly. Services like ReadTheDocs will build single repositories, which is another reason why I'm pushing to keep all the docs in one place. If we can end up with a more robust service and reduce our maintenance burden at the same time, that's a win in my books, even if it comes at some cost from combining all documentation into one repository.

Another benefit: you can have separate permissions for documentation contributors and code contributors, because they're separate repositories.

[robbieaverill]

Re-visiting this again- we need to find a solution for this. The supported module maintainers will routinely remove branches such as 3.2 for a module that is no longer in active support under that version. This tends to break the userhelp website, which pulls in documentation for that version. I'm not clear at the moment what the best way forward for that is - perhaps it is to use tags instead of branches (tags will always exist, we never delete them) but we'd need to ensure that they contain the docs folder.

We've also been deleting major version branches from SilverStripe 3 modules (such as 3) because we don't want any more features in those versions, so that also isn't an option to fall back to.

I'll have a play and see how feasible it would be to get it running on tags instead.

[robbieaverill]

Good news is we can use tags out of the box. Most of the modules I checked (quickly) exclude docs from distributable packages, but the way we clone the repositories doesn't honour this so it doesn't matter.