A GNU Binutils wiki

A GNU Binutils wiki

[Nick Clifton]

Hi Guys,

   I am in the process of creating a wiki for the binutils:

     https://sourceware.org/binutils/wiki/HomePage

   It is still bare bones at the moment, but I am hoping to build it
   up over time.  Actually to be honest I am hoping that all of us
   will help to build it up over time.

   This was inspired by some conversations and talks at this year's
   GNU Tools Cauldron.  The intent is to provide a site for helping
   newcomers and experts alike with using and contributing to the
   GNU binutils.  Ideally attracting new contributors in the process
   and making it easier for existing contributors to get their
   patches approved and committed.

   The wiki is hosted on the sourceware site, but I do not know if
   this means that people with write permission for the git repository
   can also edit the wiki directly.  If not, or if anyone without
   write permission also wants to contribute, then I am sure that a
   quick email to the overseers will sort things out.

Cheers
   Nick

Re: A GNU Binutils wiki

[Joel Brobecker]

Hi Nick,

>   I am in the process of creating a wiki for the binutils:
> 
>     https://sourceware.org/binutils/wiki/HomePage
> 
>   It is still bare bones at the moment, but I am hoping to build it
>   up over time.  Actually to be honest I am hoping that all of us
>   will help to build it up over time.
> 
>   This was inspired by some conversations and talks at this year's
>   GNU Tools Cauldron.  The intent is to provide a site for helping
>   newcomers and experts alike with using and contributing to the
>   GNU binutils.  Ideally attracting new contributors in the process
>   and making it easier for existing contributors to get their
>   patches approved and committed.
> 
>   The wiki is hosted on the sourceware site, but I do not know if
>   this means that people with write permission for the git repository
>   can also edit the wiki directly.  If not, or if anyone without
>   write permission also wants to contribute, then I am sure that a
>   quick email to the overseers will sort things out.

The question about write access had me think about how things have
been for GDB's wiki. If it's the same for binutil's as it was for
GDB, then account management in the wiki is independent of
sourceware.org account management for git access, and write access
to the wiki is granted by default as long as you take the time to
create an account using the web interface. What we saw happening
is that spammers started creating accounts and creating spam pages
in our wiki. Ultimately, we elected to make the wiki readonly except
for users who request write access and whom we know. The management
was made really easy, as giving someone write privs just consists
of adding their wiki handle to the EditorGroup handle:
https://sourceware.org/gdb/wiki/EditorGroup

Hope this helps!

-- 
Joel

Re: A GNU Binutils wiki

[Mike Frysinger]

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

On 01 Nov 2022 06:44, Joel Brobecker via Binutils wrote:
> >   I am in the process of creating a wiki for the binutils:
> > 
> >     https://sourceware.org/binutils/wiki/HomePage
> > 
> >   It is still bare bones at the moment, but I am hoping to build it
> >   up over time.  Actually to be honest I am hoping that all of us
> >   will help to build it up over time.
> > 
> >   This was inspired by some conversations and talks at this year's
> >   GNU Tools Cauldron.  The intent is to provide a site for helping
> >   newcomers and experts alike with using and contributing to the
> >   GNU binutils.  Ideally attracting new contributors in the process
> >   and making it easier for existing contributors to get their
> >   patches approved and committed.
> > 
> >   The wiki is hosted on the sourceware site, but I do not know if
> >   this means that people with write permission for the git repository
> >   can also edit the wiki directly.  If not, or if anyone without
> >   write permission also wants to contribute, then I am sure that a
> >   quick email to the overseers will sort things out.
> 
> The question about write access had me think about how things have
> been for GDB's wiki. If it's the same for binutil's as it was for
> GDB, then account management in the wiki is independent of
> sourceware.org account management for git access, and write access
> to the wiki is granted by default as long as you take the time to
> create an account using the web interface. What we saw happening
> is that spammers started creating accounts and creating spam pages
> in our wiki. Ultimately, we elected to make the wiki readonly except
> for users who request write access and whom we know. The management
> was made really easy, as giving someone write privs just consists
> of adding their wiki handle to the EditorGroup handle:
> https://sourceware.org/gdb/wiki/EditorGroup

seems like it's already configured the same

can someone copy & paste the list from gdb to binutils ?
-mike

[-- Attachment #2: signature.asc --]
[-- Type: application/pgp-signature, Size: 833 bytes --]

Re: A GNU Binutils wiki

[Nick Clifton]

Hi Mike,

>> https://sourceware.org/gdb/wiki/EditorGroup
> seems like it's already configured the same

It is.

> can someone copy & paste the list from gdb to binutils ?

Now done.  Mike - could you check that I did it correctly please ?
(This is my first time administering a wiki...)

Cheers
   Nick

Re: A GNU Binutils wiki

[Mike Frysinger]

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

On 01 Nov 2022 16:47, Nick Clifton via Binutils wrote:
> Hi Mike,
> 
> >> https://sourceware.org/gdb/wiki/EditorGroup
> > seems like it's already configured the same
> 
> It is.
> 
> > can someone copy & paste the list from gdb to binutils ?
> 
> Now done.  Mike - could you check that I did it correctly please ?
> (This is my first time administering a wiki...)

i was able to edit the homepage, so lgtm
-mike

[-- Attachment #2: signature.asc --]
[-- Type: application/pgp-signature, Size: 833 bytes --]

Re: A GNU Binutils wiki

[Joel Sherrill]

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

Not to be negative but what type of content is going to go in the Wiki?

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.
It's usually much easier to keep documents in any markup system
up to date than a wiki.

This ignores that Wikis get vandalized and have spam account attempts
which doesn't seem to happen with source code in git (or cvs).

What's the process for ensuring any links in the wiki don't break?

What review processes are going to be used for content?

What's the driving content need for a wiki?

Sorry to be negative. I like the "control" in source code control
and a wiki is lacking there.

--joel

On Wed, Nov 2, 2022 at 6:49 AM Mike Frysinger via Binutils <
binutils@sourceware.org> wrote:

> On 01 Nov 2022 16:47, Nick Clifton via Binutils wrote:
> > Hi Mike,
> >
> > >> https://sourceware.org/gdb/wiki/EditorGroup
> > > seems like it's already configured the same
> >
> > It is.
> >
> > > can someone copy & paste the list from gdb to binutils ?
> >
> > Now done.  Mike - could you check that I did it correctly please ?
> > (This is my first time administering a wiki...)
>
> i was able to edit the homepage, so lgtm
> -mike
>

Re: A GNU Binutils wiki

[Nick Clifton]

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.


> 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.


> 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).


> 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.


> 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 ?


> 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 ?

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.

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.

Cheers
   Nick

Re: A GNU Binutils wiki

[Joel Brobecker]

> > 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 ?
> 
> 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.
> 
> 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.

To have perfect documentation, we'd need someone willing to act as
its curator, and that's a big job, no matter what technology you use.

FWIW I do feel that the wiki has been a positive addition for GDB.
While it hasn't been perfect, it has has lowered the barrier for
contributing changes to this part of the project's documentation.
We have had contributions from users who normally do not contribute
to the GDB project itself as well.

-- 
Joel

Re: A GNU Binutils wiki

[Joel Sherrill]

[-- 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
>
>

Re: A GNU Binutils wiki

[Luis Machado]

On 11/2/22 13:41, Joel Sherrill wrote:
> Not to be negative but what type of content is going to go in the Wiki?
> 
> 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.
> It's usually much easier to keep documents in any markup system
> up to date than a wiki.

I feel the same way about wiki's and confluence in general. If there isn't a team on top of it,
pages do go out of sync and go stale over time. Having something in-tree that can get exported to "wiki format"
would be nice.

That would sort out the permissions issue and the vandalization.

> 
> This ignores that Wikis get vandalized and have spam account attempts
> which doesn't seem to happen with source code in git (or cvs).
> 
> What's the process for ensuring any links in the wiki don't break?
> 
> What review processes are going to be used for content?
> 
> What's the driving content need for a wiki?
> 
> Sorry to be negative. I like the "control" in source code control
> and a wiki is lacking there.
> 
> --joel
> 
> On Wed, Nov 2, 2022 at 6:49 AM Mike Frysinger via Binutils <
> binutils@sourceware.org> wrote:
> 
>> On 01 Nov 2022 16:47, Nick Clifton via Binutils wrote:
>>> Hi Mike,
>>>
>>>>> https://sourceware.org/gdb/wiki/EditorGroup
>>>> seems like it's already configured the same
>>>
>>> It is.
>>>
>>>> can someone copy & paste the list from gdb to binutils ?
>>>
>>> Now done.  Mike - could you check that I did it correctly please ?
>>> (This is my first time administering a wiki...)
>>
>> i was able to edit the homepage, so lgtm
>> -mike
>>

Re: A GNU Binutils wiki

[Mike Frysinger]

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

On 02 Nov 2022 15:28, Luis Machado wrote:
> On 11/2/22 13:41, Joel Sherrill wrote:
> > Not to be negative but what type of content is going to go in the Wiki?
> > 
> > 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.
> > It's usually much easier to keep documents in any markup system
> > up to date than a wiki.
> 
> I feel the same way about wiki's and confluence in general. If there isn't a team on top of it,
> pages do go out of sync and go stale over time. Having something in-tree that can get exported to "wiki format"
> would be nice.

at that point, there isn't much diff from what we already have today:
put it in the various manuals that get built as html and pushed to
the binutils website.  "wiki format" when the source is GIT doesn't
really mean much.  the output is html either way.
-mike

[-- Attachment #2: signature.asc --]
[-- Type: application/pgp-signature, Size: 833 bytes --]

Re: A GNU Binutils wiki

[Mark Wielaard]

Hi,

On Wed, Nov 02, 2022 at 02:49:35PM +0000, Nick Clifton via Binutils wrote:
> > 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.

I think the wiki is nice for these kind of more "social" things than
direct code things. I added a little on the buildbot CI and try
builders: https://sourceware.org/binutils/wiki/Buildbot

> > 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).

However the documentation is maintained it will always be a bit of a
struggle to keep it up to date. The advantage of the wiki is that it
is updated immediately and that non-developers can update it. But for
documentation that is actually about the code it makes sense that only
actual developers can commit it.

Now that we have the buildbot and do a build for every commit of code
we can do the same for the documentation.

How are the current code snapshots created? How is the documentation
uploaded at release time?

We can automate both and publish them on a special buildbot worker
under something like snapshots.sourceware.org/bintuils to keep them
current and so everybody can immediately see how the documentation
looks.

Cheers,

Mark

Re: A GNU Binutils wiki

[Nick Clifton]

Hi Mark,

>> 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 ? 

> How are the current code snapshots created? 

I think that there is a cron job on sourceware that creates the snapshots.

> How is the documentation uploaded at release time?

By hand. :-)

I have a procedure outlined in the binutils/README-how-to-make-a-release
document that I follow whenever I need to update the documentation.


> We can automate both and publish them on a special buildbot worker
> under something like snapshots.sourceware.org/bintuils to keep them
> current and so everybody can immediately see how the documentation
> looks.

That would be nice.  Would it involve taking up a lot of disk space ?
(Ie for how long would these snapshots last ?)

Cheers
   Nick

Re: A GNU Binutils wiki

[Mark Wielaard]

Hi Nick,

On Wed, Nov 30, 2022 at 11:03:12AM +0000, Nick Clifton via Binutils wrote:
> > How are the current code snapshots created?
> 
> I think that there is a cron job on sourceware that creates the snapshots.

I can find the gdbadmin cron job that creates gdb snapshots, but it
looks like you create the binutils snapshots by hand and upload them
to https://sourceware.org/pub/binutils/snapshots/

It would be nice to automate this a bit more either with a real
cronjob or a specific buildbot worker.

> > How is the documentation uploaded at release time?
> 
> By hand. :-)
> 
> I have a procedure outlined in the binutils/README-how-to-make-a-release
> document that I follow whenever I need to update the documentation.

Nice. I saw you just updated for the next release.  We can automate
some steps of that. Specifically 9. Create an initial
pre-release. Which can be a build script for the buildbot that can
create a snapshot each commit or day.

About

  12. Build various different toolchains, test them and nag
      maintainers to fix any testsuite failures for their
      architectures...

Which toolchains/architectures are that? Are any of them missing from:
https://builder.sourceware.org/buildbot/#/builders?tags=binutils

BTW. binutils-debian-i386, binutils-fedora-arm64 and
binutils-fedora-s390x do show some testsuite failures.

> > We can automate both and publish them on a special buildbot worker
> > under something like snapshots.sourceware.org/bintuils to keep them
> > current and so everybody can immediately see how the documentation
> > looks.
> 
> That would be nice.  Would it involve taking up a lot of disk space ?
> (Ie for how long would these snapshots last ?)

binutils snapshots are ~24MB, documentation ~18MB. So if we do one a
day that is ~1GB a month. And since it looks like you recently added
the option to create reproducible tarballs we don't really need to
keep all of them since people could recreate them from a git checkout.

Cheers,

Mark

Re: A GNU Binutils wiki

[Nick Clifton]

Hi Mark,

>>> How are the current code snapshots created?
>>
>> I think that there is a cron job on sourceware that creates the snapshots.
> 
> I can find the gdbadmin cron job that creates gdb snapshots, but it
> looks like you create the binutils snapshots by hand and upload them
> to https://sourceware.org/pub/binutils/snapshots/

Ah - yes - that does indeed appear to be the case.  I think that in the
past there was a cron job that would create daily snapshots, but I guess
that it went away.

> It would be nice to automate this a bit more either with a real
> cronjob or a specific buildbot worker.

I would be happy for that to happen.  Can I just say "pretty please" ?
or do you need me to do something ?


> About
> 
>    12. Build various different toolchains, test them and nag
>        maintainers to fix any testsuite failures for their
>        architectures...
> 
> Which toolchains/architectures are that? Are any of them missing from:
> https://builder.sourceware.org/buildbot/#/builders?tags=binutils

Lots!  I build about 100 different combinations in my local test farm.
Most are slightly obscure configurations or targets however, so I would
not worry too much about them.  There are a few that would be nice to
see added to your buildbot farm however, should you have the capacity:

   aarch64-linux-gnu
   mipsel-linux-gnu
   riscv64-elf


>>> We can automate both and publish them on a special buildbot worker
>>> under something like snapshots.sourceware.org/bintuils to keep them
>>> current and so everybody can immediately see how the documentation
>>> looks.
>>
>> That would be nice.  Would it involve taking up a lot of disk space ?
>> (Ie for how long would these snapshots last ?)
> 
> binutils snapshots are ~24MB, documentation ~18MB. So if we do one a
> day that is ~1GB a month. And since it looks like you recently added
> the option to create reproducible tarballs we don't really need to
> keep all of them since people could recreate them from a git checkout.

That makes sense.  So if you are willing to make it happen that would be
grand.

Cheers
   Nick