Re: A GNU Binutils wiki

[Joel Sherrill <joel@rtems.org>]

[-- Attachment #1: Type: text/plain, Size: 5964 bytes --]

On Wed, Nov 2, 2022 at 9:49 AM Nick Clifton <nickc@redhat.com> wrote:

> Hi Joel,
>
> > Not to be negative but what type of content is going to go in the Wiki?
>
> Well I am hoping that there will be two types of content:
>
>   1. Things that will encourage people to contribute to the binutils.
>   2. Information that will help binutils users solve their problems
>      (without having to post questions to the mailing list).
>
>
> > Over at RTEMS, I've become quite disillusioned with Wikis for most
> > content. Not being integrated with the source processes, version
> > control, and releases, it can become out of sync and out of date.
>
> To be fair I am expecting that much of the content will not be that
> sensitive.  Things like the descriptions of what the tools do, how to
> contribute changes, where to ask for help, the history of the project
> and so on.  These are all fairly static.
>

That should be OK for the wiki.

We have the somewhat unique requirement for a free software project that
RTEMS has been through IV&V for safety applications multiple times so the
how to contribute, patch process, etc are in a Software Engineering Guide.
This
also includes our coding standard and test procedure. But we want our
processes
documented sufficiently for that IV&V step.

https://docs.rtems.org/branches/master/eng/index.html

We also are building up requirements for RTEMS and ESA has released the
first Qualification Data Packs (QDP) for RTEMS on specific hardware.

https://rtems-qual.io.esa.int/

I wouldn't push these practices on any other project but there are positive
attributes to the heavy weight development processes.


>
>
> > It's usually much easier to keep documents in any markup system
> > up to date than a wiki.
>
> Would you feel happier if the text for the wiki was kept in the sources
> and then uploaded to the site on a semi-regular basis ?  (eg when releases
> are made, or once a month, or some other schedule).
>
>
> > This ignores that Wikis get vandalized and have spam account attempts
> > which doesn't seem to happen with source code in git (or cvs).
>
> Ideally the fact that only people in the EditorGroup can make changes
> to the wiki should help to reduce/eliminate this problem.
>

That will help.

>
>
> > What's the process for ensuring any links in the wiki don't break?
>
> There isn't one.
> (I would assume that broken links would be reported and fixed, but
> there is no formal scheme for verifying that any links continue to
> work).
>

I would hope that also but I suspect we all have seen things broken
for over a decade and wondered why no one ever complained. :)


>
>
> > What review processes are going to be used for content?
>
> Similar to the current process for patch review would be my assumption.
> People with EditorGroup access can make changes directly.  Others
> would submit changes for review and eventual application.
>

OK

>
>
> > What's the driving content need for a wiki?
>
> Apparently wikis have been successful for other projects, eg glibc,
> and I am trying, in a small way, to bring the GNU Binutils up to date.
>
> It was pointed out for example that we do not have a Code of Conduct
> or a Mission Statement.  Now some people might feel that these things
> are not really necessary, but would it hurt to have them ?  And if we
> do have them, where would a naive, unexperinced-with-the-binutils
> person look for them ?
>

I guess we all are old school and know what binutils is suppose to
do and how to behave but these are unfortunately good to have
because they scope discussions on what to add and give a framework
to address bad behavior.

>
>
> > Sorry to be negative. I like the "control" in source code control
> > and a wiki is lacking there.
>
> That's fine.  It is good to have an opinion and I am glad that you
> are willing to express it.  My counter would be - what can we do instead ?
>

We've moved a lot to things like a Users Guide, Contributors Guide, Software
Engineering Guide, etc. But if the wiki is just another approach to a better
binutils project web page, then it's ok.

We still have content in our wiki also. I don't know how things like our
GSoC tracking pages would work outside a wiki.


>
> I know that most of the information intended for the wiki can be found
> by digging through the sources, but that will not work for people who
> are not already deeply familiar with the binutils.  So I wanted to create
> a place where people with at least some experience with other part(s) of
> the GNU toolchain would expect to be able to find information on the
> binutils.
>
> Plus I wanted to provide a location for binutils users and contributor to
> be able to provide their own content.  Descriptions of the problems that
> they encountered whilst porting the binutils; advice for users of small
> devices that need custom linker scripts in order to work properly and so
> on.
>

We have a Porting Guide which is analogous to porting binutils.

The small devices advice could be in a Users Guide. It isn't just linker
scripts, building with per section functions and data items helps a lot
also. Even using gcc's -Os is helpful.

But small is a challenge and we've found avoiding printf() and functions
like mktime() is important also.

Anyway, it's a broad topic.

>
> Plus a location with responses to frequently asked questions(tm) which we
> can use when answering those I-have-found-a-name-mangling-bug and
> why-doesn't-the-assembler-auto-correct-my-bugs type questions on the
> mailing list.
>

A wiki will be good for this. But it also is just using a wiki like a
project
webpage for more or less static content.

As long as it isn't an excuse to add to an existing manual or add a new
manual, it's probably OK. We started a page for each Board Support
Package, had pages on using git with the RTEMS Project, and more
which turned out to be too far into the "should be in a manual"
category.

--joel

>
> Cheers
>    Nick
>
>