kicad-doc-devs team mailing list archive

[Jon Evans <jon@xxxxxxxxxxxxx>]

My view is that the development team (including those working on code and
those working on documentation, sometimes the same people and sometimes
different) need a place to stage documentation for future releases.
I think KiCad will almost always be in a situation where the development
version *could* have different features than the released version, and it
would be good to have "nightly builds" of the docs available so that we
don't delay writing and checking documentation until the very last minute.

But Nick's point is also good, in that this takes more effort from
volunteers.

-Jon

On Thu, Jan 9, 2020 at 7:32 PM <f.dos.santos@xxxxxxx> wrote:

> Thanks, interesting reading.
>
> Obviously I think this wasn't a good move as it confuses users.
> I'm in favour of adding documentation for new features only when the
> release cycle starts (when features are stable and frozen).
>
> IMHO not having new features documentation ready for nightly build users
> is not a big deal, they are brave enough to live on the edge, they can live
> without documentation :-)
>
>
> ----- Mail original -----
> From: "Jon Evans" <jon@xxxxxxxxxxxxx>
> To: "f dos santos" <f.dos.santos@xxxxxxx>
> Cc: kicad-doc-devs@xxxxxxxxxxxxxxxxxxx
> Date: 10/01/2020 00:53:46
> Subject: Re: [Kicad-doc-devs] Connections buses in eeschema documentation
> are "indated"
>
>
>
>
> Some previous discussion: https://github.com/KiCad/kicad-doc/issues/719
>
>
>
>
>
>
> On Thu, Jan 9, 2020 at 6:45 PM < f.dos.santos@xxxxxxx > wrote:
>
>
> Hi,
>
> People can say that some documentation are outdated but for buses
> connections it's the other way around.
> I'm pretty sure "indated" it's not a word ;-)
>
> The eeschema docs section 6.5.3 Connections (Buses) for KiCad v5.1.5
> contains instructions for features specific to v6.0 :
>
> -
> https://docs.kicad-pcb.org/5.1.5/en/eeschema/eeschema.html#wires-buses-labels-power-ports
>
> This has been reported as issue 772 and 773 :
>
> - https://gitlab.com/kicad/services/kicad-doc/issues/773
> - https://gitlab.com/kicad/services/kicad-doc/issues/772
>
>
> Clearly, those commits should'nt have been included on 5.1 releases :
> - 5fd00e738 Initial documentation for bus upgrades
> - 29ed809ec Note new behavior of conflicting labels
> - d27c40092 Add documentation for Migrate Buses dialog
>
>
> I could be wrong (I'm new here) but I think the current git workflow for
> the doc team is :
> 1) master is the current documentation, every improvements and pull
> request goes on master (to make life easier for translators, there's only
> master that matters)
> 2) when KiCad reach features freeze, the new features are documented again
> against master and translators do their work until official release
> 3) official release, master gets tagged with the same version number like
> all Kicad repos
> 4) if we need to work on previous documentation, we could branch out of a
> specific release. Master is still the current documentation and we're back
> to step 1).
>
>
> So my question is how could we solve those gitlab issues ?
> Do we leave documentation with mistakes until next KiCad release ?
>
> When are docs.kicad-pcb.org website updated ? I assume the website can be
> updated between official KiCad releases (if we haven't one we could adopt a
> strategy to schedule documentation update to the website, for example every
> 2 months).
>
>
> If we stick to the workflow above, we have to rollback those 3 commits and
> put them back in only when v6.0 reach features freeze.
>
> I'm open to better ideas.
>
>
> Francisco
>
> --
> Mailing list: https://launchpad.net/~kicad-doc-devs
> Post to : kicad-doc-devs@xxxxxxxxxxxxxxxxxxx
> Unsubscribe : https://launchpad.net/~kicad-doc-devs
> More help : https://help.launchpad.net/ListHelp
>