|author||Pritiah Jain <email@example.com>||2018-12-03 02:43:01 +0530|
|committer||Joel Sherrill <firstname.lastname@example.org>||2018-12-17 18:45:49 -0600|
management: Convert TBD to rest Format (GCI 2018)
Diffstat (limited to 'eng/why-contribute.rst')
1 files changed, 151 insertions, 0 deletions
diff --git a/eng/why-contribute.rst b/eng/why-contribute.rst
new file mode 100644
@@ -0,0 +1,151 @@
+.. comment SPDX-License-Identifier: CC-BY-SA-4.0
+.. COMMENT: COPYRIGHT (c) 2018.
+.. COMMENT: RTEMS Foundation, The RTEMS Documentation Project
+If you are writing a major extension to RTEMS, such as a port
+to a new CPU family or model, a new target board, a major rewrite
+of some existing component, or adding some missing functionality,
+please keep in mind the importance of keeping other developers informed.
+Part of being a good cooperating member of the RTEMS development team is the
+responsibility to consider what the other developers need in order
+to work effectively.
+Nobody likes to do a lot of work and find it was duplicated effort.
+So when you work on a major new feature, you should tell
+email@example.com what you are working on, and give
+occasional reports of how far you have come and how confident
+you are that you will finish the job. This way, other developers
+(if they are paying attention) will be aware which projects would
+duplicate your effort, and can either join up with you, or at
+least avoid spending time on something that will be unnecessary
+because of your work. If, for whatever reason, you are not in a
+position to publicly discuss your work, please at least privately
+let a Steering Committee member know about it so they can look
+out for duplicated effort or possible collaborators.
+You should also monitor the
+`RTEMS Mailing Lists <https://devel.rtems.org/wiki/TBR/Website/RTEMSMailingLists>`_.
+to see if someone else mentions working on a similar
+project to yours. If that happens, speak up!
+If you are thinking of taking a contract to develop changes
+under a temporary delayed-release agreement, please negotiate
+the agreement so that you can give progress reports before the
+release date, even though you cannot release the code itself.
+Also please arrange so that, when the agreed-on date comes,
+you can release whatever part of the job you succeeded in doing,
+even if you have not succeeded in finishing it.
+Someone else may be able to finish the job.
+Many people have done RTEMS ports or BSPs on their own, to a wide
+variety of processors, without much communication with the RTEMS
+development team. However, much of this work has been lost over
+time, or have proven very hard to integrate. So, what we're asking
+is that, to the maximum extent possible, you communicate with us
+as early on and as much as possible.
+Common Questions and Answers
+Here are some questions RTEMS porters may have with our answers to
+them. While the focus here is on new ports and BSPs, we believe that
+the issues are similar for other RTEMS development efforts including
+student efforts to implement new algorithmic optimizations.
+''Our engineers understand our target environment better than anyone
+else, and we have a tight schedule. Why should we work with the RTEMS
+developers, when we can get the code out faster by whacking it out on our own?''
+You understand your target environment better than anyone else.
+However, the RTEMS developers understand RTEMS better than anyone
+else; furthermore, the RTEMS developers tend to have a wide breadth
+of experience across a large number of processors, boards, peripherals,
+and application domains. It has been our experience that few problems
+encountered in embedded systems development are unique to a particular
+processor or application. The vast majority of the time an issue that
+arises in one project has also shown up in other projects.
+The intimate knowledge of RTEMS internals as well as a wide breadth of
+embedded systems knowledge means that there is a good chance that at
+least one RTEMS developer has already addressed issues you are likely
+to face when doing your port, BSP, or application. The developers can
+help guide you towards a workable long term solution, possibly saving
+you significant time in your development cycle.
+If getting the sources into the official RTEMS distributions is one of
+your goals, then engaging other RTEMS developers early will also likely
+shorten your development time. By interacting as early as possible you
+are more likely to write code which can be easily accepted into the official
+sources when you are finished. If you wait until you think you are done
+to begin interacting with the RTEMS team, you might find that you did
+some things wrong and you may have to rewrite parts of your RTEMS port,
+which is a waste of your valuable time.
+''Why should we care if our port is integrated into the official
+RTEMS sources? We can distribute it ourselves to whoever is interested.''
+Yes, the GNU GPL allows you to do that. But by doing so, you end up
+having to maintain that code yourself; this can be a significant
+effort over time as the RTEMS sources change rapidly.
+You also lose the advantage of wider exposure by including your port
+in the official RTEMS sources maintained by the RTEMS Project.
+The wider exposure in the RTEMS developer and tester community will
+help keep your work up to date with the current sources. You may even
+find that volunteers will run the ever-growing test suite on your port
+and fix problems during the development cycle -- sometimes without your
+It has been our experience that integrated ports tend to ultimately
+be of better quality and stay up to date from release to release.
+''Why should we communicate up front? We're happy to let the
+RTEMS developers integrate our stuff later.''
+See above. It will save work for you over both the short and the
+long term, and it is the right thing to do.
+''Aspects of my target environment that my application exploits
+are still under NDA.''
+Nevertheless, if the target hardware is built of any commercial parts
+that are generally available including, but not limited to, the CPU
+or peripherals, then that portion of your work is still of general use.
+Similarly, if you have written software that adheres to existing API or
+interface standards, then that portion is also of general use.
+Our experience is that most embedded applications do utilize a custom
+mix of hardware and application, but they are built upon layers of hardware
+and software components that are in no way unique to the project.
+If you are porting to an unreleased CPU family or model, then just
+announcing it is important because other RTEMS users may be planning
+to use it and some of them may already be trying to port RTEMS on
+their own. Your customers might be happier to know that your port
+will eventually be available. Also, there is no requirement that RTEMS
+include all features or ports at any particular time, so you are encouraged
+to submit discrete pieces of functionality in stages.
+Assume that your processor has some new functionality or peripherals.
+However that functionality is still covered by NDA, but the basic core
+architecture is not. It is still to your advantage to go ahead and work
+with the developers early to provide a "base port" for the CPU family.
+That base port would only use the publicly available specifications
+until such time as the NDA is lifted. Once the NDA is lifted you can
+work with the developers to provide the code necessary to take
+advantage of the new functionality.
+Ultimately, cooperating with the free software community as early as
+possible helps you by decreasing your development cycle, decreasing
+your long term maintenance costs and may help raise interest in your
+processor by having a free compiler implementation available to
+anyone who wants to take a look.
+Finally, please note that GPL-covered code may not be distributed
+under an NDA, as explained by Richard Stallman in