fuel-dev team mailing list archive

[Dmitry Borodaenko <dborodaenko@xxxxxxxxxxxx>]

I agree, tracking revision history for design documents is important,
and having RST in a Git repo is the best way to achieve that.

Maybe we can add a design section to the fuel-docs repo, and agree
that once the design is finalized (which typically would be after
implementation has started but before it's completed) it should be
moved from Google Drive to Git? That way, we can have a fast and
efficient discussion of design while it's still being changed rapidly,
and we end up with a design document that we can easily reference and
reuse from our documentation site once design is more or less
completed.

On Mon, Nov 11, 2013 at 3:03 AM, Bogdan Dobrelya <bdobrelia@xxxxxxxxxxxx> wrote:
> On 11/11/2013 12:19 PM, Mike Scherbakov wrote:
>
> Fuel folks,
> if you use google documents and put your design for any enhancement there,
> we need to make sure such documents are never lost in order to avoid
> duplication of work.
>
> Find or create corresponding blueprint on launchpad
>
> Make sure it has good description (issue statement, main idea on how it is
> going to be addressed)
> Blueprint has reference link to the google doc with design
>
> Make sure your GoogleDoc has following permissions:
>
> Anyone can comment
> Core team can edit
>
> I would prefer to use wiki where possible, and actually use google docs at
> the phase when a lot of collaboration is needed (google docs have great
> comments feature).
>
> Thank you,
> --
> Mike Scherbakov
>
>
> I believe we have to consider the cases for design docs are being updated
> while implementation is in progress:
>
> - How we can track the 'new changes' vs 'done'?
>
> I suggest we have to use some tools for github (and/or gerrit) integration
> with our design docs, thus docs should be kept in any "diffable" way (f.e.
> in RST format?), so we can issue git diff against any design docs any time
> to see what has been changed since the last commits, as well to address them
> in implementation related activities.
>
> F.e. the history of design and implementation could look like this:
>
> docs:
> 54900c8 - Bogdan Dobrelya, 32 minutes ago : Update the structure format for
> astute.yaml for feature1
> 11ec45b - Vladimir Kuklin, 5 days ago : Create the structure format for
> astute.yaml for feature1
>
> Implementation (topic branch):
> fe1a2a0 - Vladimir Kuklin, 10 minutes ago : Implement 54900c8 of feature1
> design
> 491382d - Sergey Vasilenko, 4 days ago : Implement 11ec45b of feature1
> design
>
> I believe the active collaboration always suggests active changes in design,
> but development/fix process have a tendency to start at the very early
> stages of design and never stops as well ... Thats why, IMHO, it is critical
> to track design docs changes appropriately.
>
> --
> Best regards,
> Bogdan Dobrelya,
> Researcher TechLead, Mirantis, Inc.
> +38 (066) 051 07 53
> Skype bogdando_at_yahoo.com
> 38, Lenina ave.
> Kharkov, Ukraine
> www.mirantis.com
> www.mirantis.ru
> bdobrelia@xxxxxxxxxxxx
>
>
> --
> Mailing list: https://launchpad.net/~fuel-dev
> Post to     : fuel-dev@xxxxxxxxxxxxxxxxxxx
> Unsubscribe : https://launchpad.net/~fuel-dev
> More help   : https://help.launchpad.net/ListHelp
>



-- 
Dmitry Borodaenko