[Bf-docboard] Getting involved and workflow questions

[Campbell Barton]

Hi Helmar,

On Thu, Mar 26, 2015 at 2:47 AM, Helmar Suschka <development at suschka.de> wrote:
> Hello,
>
> I’m willing to jump in with contributing to the Blender documentation
> project. I have a few questions before I can start working, most of
> them related to the general workflow and collaboration between
> contributers.
>
> The Sphinx/reST stuff is no entry barrier for me since I already work
> a lot with similar publishing solutions (mostly AsciiDoc and its
> DocBook toolchain). But I’ll have to adjust to the obstacles the use
> of Subversion introduces.
>
> 1) How to do quick “drive-by” changes?
>
> I’m used to do spontaneous corrections and improvements all over the
> place when I see the opportunity, e.g. when I’m working with Blender
> and the manual and stumble upon something (bad description, typos,
> layout errors, etc.). I’d just fix it right away. So -- without
> branching and local commits, is there a way to do this independently of
> other work in progress? Would it affect other contributors that may be
> working on different sections? Or shouln’t I do this at all because
> it’s too complicated to coordinate with the current system?

We don't have anything comprehensive in this respect.

Steps are ...

- Checkout SVN repo
- Edit locally

- Submit patch OR Commit directly

> 2) How to collaborate with someone on the same content?
>
> There are some broader tasks claimed where I’m unsure if I can do
> something that may overlap with them or have to ask first every time.
> There’s no way to see more detailed if someone is actually working
> right now (has made local changes that are not visible to others yet)
> and on what exactly. This could block whole sections from faster
> improvement by discouraging contributors to touch anything related to
> not do double or otherwise useless work. How can we get around this in a
> least time-consuming way?

This normally happens in diff-review, if someone claimed a task and
they aren't active you could comment.
There is really quite a lot of text in the manual, chances you work on
the same area isn't that high (Blender's code is far more actively
developed and its not often a problem there either).

If you see an area to improve - just work on it, dont let others block
you - unless exceptional reason.

> 3) How to handle WIP changes without freezing everything local?
>
> No one can see changes unless they’re either committed or provided as a
> diff. Committing directly means having things in production stage
> without any review (not good, and it forces bigger, complete commits
> instead of more granular ones). Providing a diff for review on every
> change freezes any further local changes until review is complete
> (otherwise you’d mess up later diff creation). This seems to be a
> hurdle for efficient parallel proof-reading while other work can
> continue.

For now we just accept limits of SVN, if you're not sure about a
change - you can submit for review first.

If you are making many changes you would want commit access, so - if
you contribute some patches which  show you can make improvements, we
can add you to the project.
They don't have to be huge patches either.

One minor point - theres no reason to for bigger commits, small
commits in SVN go fine too.

> Maybe there are already solutions to some of that or we can find some.
> It’s all about being able to work fluently and spontaneously when
> there is time for it, without too much administration overhead.

If you like to get involved probably best just to focus on an area
(even a small one) and come up with a patch. Don't worry about
collisions.

> I’d like to work on some of the basics first to get used to it
> (unless it collides with Gaia’s work, see question 2). I found some
> naming inconsistencies in there as well as redundant passages and
> unfitting images.

Sounds good, let us know how you go.

> Later on I’d move to other sections and especially have some focus on
> video editing.
>
> I’m looking forward to contribute my first changes soon.

Cheers,
- Campbell

> --
> - Helmar
> _______________________________________________
> Bf-docboard mailing list
> Bf-docboard at blender.org
> http://lists.blender.org/mailman/listinfo/bf-docboard



-- 
- Campbell