From 32a4a0adedbae8c502719ccd6dbf7b0349b67af1 Mon Sep 17 00:00:00 2001 From: Pritiah Jain Date: Mon, 3 Dec 2018 02:43:01 +0530 Subject: management: Convert TBD to rest Format (GCI 2018) --- eng/management.rst | 5 +- eng/why-contribute.rst | 151 +++++++++++++++++++++++++++++++++++++++++++++++++ 2 files changed, 154 insertions(+), 2 deletions(-) create mode 100644 eng/why-contribute.rst diff --git a/eng/management.rst b/eng/management.rst index 2b03dee..a71167a 100644 --- a/eng/management.rst +++ b/eng/management.rst @@ -7,8 +7,8 @@ Software Development Management ******************************* -TBD - Convert https://devel.rtems.org/wiki/TBR/Website/WhyContribute to Rest -TBD - and insert here +.. COMMENT:TBD - Convert https://devel.rtems.org/wiki/TBR/Website/WhyContribute to Rest +.. COMMENT:TBD - and insert here .. COMMENT: Subsections .. toctree:: @@ -18,3 +18,4 @@ TBD - and insert here coding change-management issue-tracking + why-contribute diff --git a/eng/why-contribute.rst b/eng/why-contribute.rst new file mode 100644 index 0000000..619a255 --- /dev/null +++ b/eng/why-contribute.rst @@ -0,0 +1,151 @@ +.. comment SPDX-License-Identifier: CC-BY-SA-4.0 + +.. COMMENT: COPYRIGHT (c) 2018. +.. COMMENT: RTEMS Foundation, The RTEMS Documentation Project + + +Why Contribute? +*************** + +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 +rtems-users@www.rtems.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 `_. +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 +intervention. + +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 +http://gcc.gnu.org/ml/gcc/2001-07/msg01342.html. -- cgit v1.2.3