[HTML] Patch to contribute.html: add section about new backends

[Gerald Pfeifer]

On Mon, 21 Jun 2004, Giovanni Bajo wrote:
> this part of my big patch to contribute.html went uncommented, so I
> would tend to assume it is mostly OK. I'm sure Steven will like to
> double check it, but I guess it matches his effort on removing old
> targets and documenting requirements for new backends.

Steven, any comments?

> Index: contribute.html
> ===================================================================
> + <p>Notice that GCC now requires an ISO C90 compiler to bootstrap,
> + so there is no need anymore to make the code conform to K&R C for
> + either new files or existing code (no need for the <code>PARAMS</code>
> + macro in function prototypes, <code>#elif</code> is available, etc.).</p>

I'd omit "anymore" and "either new files or existing code" to try and
keep our relevant docs relatively small.

> + <p>Historically, GCC has been very open to submissions of new backends. While
> + this is obviously a good thing, it causes many maintainance headhaches since
> + it is very easy for a backend to not be carefully maintained, and become
> rotten
> + code very quickly. In the past few releases, we have been deprecating and
> + removing many backends which were totally broken (and had been like that for
> + years).</p>
> +
> + <p>A backend which is not tested daily or at least weekly, and regulary
> + maintained, is bound to break sooner or later (and given the usual speed of
> + development, it is probably a matter of a few months). This gives a false
> promise
> + to our users, as their code will probably not compile, and creates an
> unwanted
> + maintanance burden for the whole core, due to incomplete transitions to new
> + technologies which are added to the GCC core. For instance, some backends
> + have not yet been converted to use the new DFA for pipeline description,
> which
> + makes us unable to clean the codebase by removing the support for the old
> + pipeline description code.</p>
> +
> + <p>This is why we are currently quite cautious with respect to accepting new
> + backends. We urge you to read carefully the following guidelines and to
> follow
> + them while developing a new backend, if you intend to submit it for inclusion
> + in the official development tree.</p>

Would you mind compressing this significantly?  I'm not sure whether some 
of these statements really are the consensus (of the GCC maintainers, the
members of the gcc list, the SC), and I'd avoid too many details.

> + <li>The backend must have been carefully tested. This means a full bootstrap,
> + with all languages turned on,

I don't think we can demand this, especially not for Java and Ada.

> + follow-up patch. The summary of the testsuite run must be included in your
> + submission mail. It is not strictly necessary for all the tests to succeed,
> + but the overall view should be pretty good.</li>

This would be a new requirement.  Not that I don't think it makes sense,
but still.

> + <li>The backend must have been developed and tested on the current mainline.
> + There is no way we can accept a new backend tested on a release branch, or
> + on an old mainline.</li>

I suggest to omit "on an old mainline", and please note that we have added
backends on a release branch not too long ago.

> + <li>As any other patch, the backend must carefully follow our
> + <a href="#standards">coding standards </a> throughout the whole code. Being
> + new files is no excuse for them not to follow our standards.</li>

I'd omit everything after and including "throughout".

> + <li>All the people involved in the work must have fully completed the
> + paperwork with the FSF for copyright assignment for past and future changes.

Contributors do _not_ need to have completed exactly this way of dealing
with the copyright issue.  Just consider disclaimers and corporate
assignments.

> + <li>One or more people involved in the work must volunteer to be appointed
> + as official maintainers for the backend. This involves daily (or at least
> + weekly) testing of the backend (full bootstrap and testsuite runs, with
> + results posted to the

"regular testing"

> + <li>It is strongly preferred if the patch that adds the new backend does not
> + include many changes to the GCC core. Theoretically, the only changes which
> + should be needed are the mechanical ones (configuration system, etc.). If
> + the new backend exposed bugs in the GCC core, it is preferrable to submit
> + the patches that fix them separately from the new backend (after having
> + tested them on another, already exising, platform), either before or
> + after the backend submission.</li>

I think that before is preferrable.  And in some cases, a radically new
port will certainly also require invasive changes.

> + <li>The backend must use a RTL prolog/epilogue description for function
> + as opposed to the old text prolog/epilogue.

"functions"?

> + <li>Do not copy the documentation for target hooks from the internals
> + manual in comments preceding the hook itself. It is an unneeded duplicate
> + which is doomed to desynchronize sooner or later. You can of course
> + comment the hook about everything specific to the backend itself.</li>

Compress this one please.  As for the more specific requirements at the
end of this patch, I don't think I should approve your patch without
consensus by the community or the steering committee.

Gerald