[Arm-netbook] Documentation Proposal

[Alejandro Mery]

On 19/05/12 14:02, cnxsoft wrote:
> Hi,
>
> Since there seems to be a bit a tension regarding documentation and
> tracking changes, I would like to make a proposal about how it could be
> organized.
>
> *Software changes*
> For kernel, u-boot, tools changes, let's use Amery github account
> https://github.com/amery (if that's OK with him).

in the case of u-boot I would prefer to use the issue tracker of that 
the most maintained u-boot tree for sunxi, hno's.

https://github.com/hno/uboot-allwinner ... he also imported 
`mksunxiboot` there.

as for sunxi-tools and linux-allwinner, absolutely. It would also be 
nice to unify the tools repos, even if they are only simple scripts :)


> Each time code is committed there is a log entry, so If somebody wants
> to see the software changes, he could just check the log (git log could
> also refer to the corresponding mailing list thread). If need-be, a text
> based ChangeLog could be also generated automatically.

+1


> *Wiki*
> The wiki would be a good place for how-tos, such as the existing how to
> prepare an SD card
> (http://rhombus-tech.net/allwinner_a10/a10_mmc_boot/), how to compile
> the kernel (http://rhombus-tech.net/allwinner_a10/kernel_compile/).
> It can also be used introduce/describe the project, hardware, available
> software.

+1 ... but I would like to mention github projects also include a wiki 
which can be used to document generic procedures (not detailed how-tos), 
directly bound to the corresponding sources.


> *Mailing list*
> IMHO, the mailing list should be used for all sort of exchange. If
> somebody post a patch for example, and it's accepted, it will be
> committed to github (and there will be a log for that).
> For tools and scripts,, they could also be added to github.

+1 sure, the MLs are be for discussions, and work far better than the 
thread on an issue tracker for that imnsho. wiki for longer term 
documentation and hackless how-tos, is something needs a patch this 
patch that it is a software bug.

>
> *Bug Tracking*
> Amery suggested to use the issues tracker in github. That's fine, but
> there may be some things that are user-space related (e.g. X11
> acceleration, video decoding, rootfs modifications), so I'm not sure
> it's ideal to use github for those.

right, it actually might be a good idea to turn a version the leaked 
tools repo (un-removing sun5i support) and an open bsp project and keep 
user-space related issues there.

> On a slightly different topic, it seems we now focus development on the
> kernel/bootloader, but nothing is done on Linux distributions yet. It
> might be a good idea to select some distributions e.g. Ubuntu, Debian.
> (Pick your choice).
> We don't need to take care of the main rootfs which can be retrieved
> online, but AllWinner A10 specific items could be stored in hardware
> packs as Linaro does with their supported platform, and simply use a
> tool (called linaro-media-create) to create an image based on the rootfs
> and the hardware pack. We could also have the A10 hardware pack in
> github, where changes would be documented (log after each commit) and
> use github issue tracker for bugs/feature requests.

my plan at least was that after allwinner-v3.0-android-v2 gets 
functional enough make an android-less linux-v3.3-sunxi branch with 
sun3i, sun4i and sun5i support to be usable from distros, specially 
linaro 12.04 (personal choice) and possibly android-5.0, and a generic 
linux-sunxi aimed at mainlining more than real people usage.


>
> For example, software changes made to the software would be not
> documented in the Wiki as details about the changes are accessible in
> github, but the method to retrieve the different binaries, how-to create
> an image and possibly a Changelog between releases would be added to the
> WiKi.

+1