Difference between revisions of "Development Introduction"
DangerGround (talk | contribs) (→Development techniques: strip out some not so useful information) |
(Move Documentation to top and Links to bottom) |
||
| Line 1: | Line 1: | ||
There are several ways to contribute to the development of ReactOS. The most often encountered problem is not knowing where to begin or what to do. If you are able to program or understand the technical information that is pertinent to this project, helping the development can be easy. | There are several ways to contribute to the development of ReactOS. The most often encountered problem is not knowing where to begin or what to do. If you are able to program or understand the technical information that is pertinent to this project, helping the development can be easy. | ||
| + | |||
| + | == Documentation == | ||
| + | |||
| + | There are some important points if you'd like to help document ReactOS: | ||
| + | # Make sure the documentation doesn't exist yet (if it does, help improve it). | ||
| + | # Respect [[Wikipedia:Clean room design|clean room reverse engineering]] practices. | ||
| + | # Add your knowledge to a place where the other developers can find it. | ||
== Test ReactOS == | == Test ReactOS == | ||
| Line 19: | Line 26: | ||
Considering ReactOS is alpha quality software, there is a lot of [[Missing ReactOS Functionality|missing functionality]] that Windows operating systems have. Before starting a project to implement something, find out if another person is working on the same thing. If you find that someone is already working on it, ask if any assistance is needed for what specifically is being worked on or a related project. Plenty of times a person will start to implement something and never finish before moving to something else. Make sure you stay committed to what you are going to implement, and do not be afraid to ask for assistance if you need help with something. | Considering ReactOS is alpha quality software, there is a lot of [[Missing ReactOS Functionality|missing functionality]] that Windows operating systems have. Before starting a project to implement something, find out if another person is working on the same thing. If you find that someone is already working on it, ask if any assistance is needed for what specifically is being worked on or a related project. Plenty of times a person will start to implement something and never finish before moving to something else. Make sure you stay committed to what you are going to implement, and do not be afraid to ask for assistance if you need help with something. | ||
| − | == | + | == Patches == |
| − | |||
| − | |||
| − | |||
| − | |||
| − | |||
| − | |||
| − | |||
| − | |||
| − | |||
| − | |||
| − | |||
| − | |||
A patch is a set of changes to existing source code. The changes in a patch can be merged into existing source code. This process is referred to as applying a patch (to source code). Which changes a patch contains and the way the patch is structured can have significant impact on the consequences that can happen from applying the patch. Below are a few recommendations on how to create and use patches. | A patch is a set of changes to existing source code. The changes in a patch can be merged into existing source code. This process is referred to as applying a patch (to source code). Which changes a patch contains and the way the patch is structured can have significant impact on the consequences that can happen from applying the patch. Below are a few recommendations on how to create and use patches. | ||
=== Create small patches === | === Create small patches === | ||
| + | |||
Reviewing has proven to be an effective method of discovering bugs, so one should strive towards creating patches that are easy to review. Unfortunately, [http://www.eurekalert.org/pub_releases/2005-03/aps-hmc030805.php humans are terrible at tracking large amount of information]. Therefore keep the patches as small as possible to make reviewing easier. | Reviewing has proven to be an effective method of discovering bugs, so one should strive towards creating patches that are easy to review. Unfortunately, [http://www.eurekalert.org/pub_releases/2005-03/aps-hmc030805.php humans are terrible at tracking large amount of information]. Therefore keep the patches as small as possible to make reviewing easier. | ||
=== Put only related changes in a patch === | === Put only related changes in a patch === | ||
| + | |||
Putting only related changes in a patch will make reviewing easier as the reviewer needs to recall less information about the existing source code that is changed. | Putting only related changes in a patch will make reviewing easier as the reviewer needs to recall less information about the existing source code that is changed. | ||
=== Notice the risks which are associated with applying the patch === | === Notice the risks which are associated with applying the patch === | ||
| + | |||
The risk of introducing a bug is higher with some types of changes than others. Formatting is a relatively safe change while semantic changes to complex code is a highly risky change. This means that reviewing a formatting-only patch is not as important as reviewing a patch with semantic changes to complex code (and thus it doesn't hurt so much if a formatting patch is large). When mixing safe and unsafe changes, the overall risk of introducing a bug in a given patch is the same as if the changes were spread over several patches. However, the risk of the individual patch is equal to risk of the most risky change in the patch. So if a 1 line highly risky change is hidden in a 2000 line otherwise safe patch, then the overall risk for the whole patch is highly risky. Therefore strive towards putting changes of similar risk into the same patch. | The risk of introducing a bug is higher with some types of changes than others. Formatting is a relatively safe change while semantic changes to complex code is a highly risky change. This means that reviewing a formatting-only patch is not as important as reviewing a patch with semantic changes to complex code (and thus it doesn't hurt so much if a formatting patch is large). When mixing safe and unsafe changes, the overall risk of introducing a bug in a given patch is the same as if the changes were spread over several patches. However, the risk of the individual patch is equal to risk of the most risky change in the patch. So if a 1 line highly risky change is hidden in a 2000 line otherwise safe patch, then the overall risk for the whole patch is highly risky. Therefore strive towards putting changes of similar risk into the same patch. | ||
=== Set goals for your next patch === | === Set goals for your next patch === | ||
| + | |||
To help prevent your patches from becoming too large, set one or more goals for your next patch before you start making any changes. A goal could be to refactor a part of the source code which is hard to understand. It could be to implement part or all of a new feature, or fix a bug that exists in the existing source code. If achieving the goals require too many changes and would make the patch become large and/or contain many unrelated changes, then define new goals which, when reached, would ensure that the original goals would be partially achieved. | To help prevent your patches from becoming too large, set one or more goals for your next patch before you start making any changes. A goal could be to refactor a part of the source code which is hard to understand. It could be to implement part or all of a new feature, or fix a bug that exists in the existing source code. If achieving the goals require too many changes and would make the patch become large and/or contain many unrelated changes, then define new goals which, when reached, would ensure that the original goals would be partially achieved. | ||
=== Keep focus when developing the patch === | === Keep focus when developing the patch === | ||
| + | |||
While developing a patch, it can be tempting to fix existing issues as you come across them while reading the source code. This can however quickly cause the patch to become large and contain several unrelated changes which have nothing to do with achieving the goals which were defined for the patch. Resist the temptation and put in a note in the source code instead, or (even better) put the issue in the issue tracking system. | While developing a patch, it can be tempting to fix existing issues as you come across them while reading the source code. This can however quickly cause the patch to become large and contain several unrelated changes which have nothing to do with achieving the goals which were defined for the patch. Resist the temptation and put in a note in the source code instead, or (even better) put the issue in the issue tracking system. | ||
| + | === Review Patches === | ||
| − | |||
Drupal has some tips for reviewing patches. | Drupal has some tips for reviewing patches. | ||
[http://drupal.org/patch/review Tips for reviewing patches] | [http://drupal.org/patch/review Tips for reviewing patches] | ||
| + | == Places to find information == | ||
| + | |||
| + | * [http://msdn.microsoft.com/ MSDN] - Your search should start here. | ||
| + | * [[External Documentation Links]] - Otherwise you should try to find something here. | ||
| + | * [[Techwiki:main|ReactOS Techwiki]] - Documentation provided or collected by ReactOS developers. | ||
[[Category:Development]] | [[Category:Development]] | ||
Revision as of 18:47, 21 November 2009
There are several ways to contribute to the development of ReactOS. The most often encountered problem is not knowing where to begin or what to do. If you are able to program or understand the technical information that is pertinent to this project, helping the development can be easy.
Contents
Documentation
There are some important points if you'd like to help document ReactOS:
- Make sure the documentation doesn't exist yet (if it does, help improve it).
- Respect clean room reverse engineering practices.
- Add your knowledge to a place where the other developers can find it.
Test ReactOS
Localize bugs
As code is added, changed, or removed, it is possible for unintended results to occur. These unintended results are known as bugs. By localizing bugs, developers can identify what causes the bug and what it affects. There are a variety of methods to debug ReactOS while testing it. After identifying a bug, check if it is already known about by searching Bugzilla and add any additional information to the report. If you think that it is an unidentified bug, consider filing a bug report.
Fix bugs
Instead of looking for bugs, you can also try to fix a few that are already listed on Bugzilla. Fixing bugs requires a lot more skill than simply searching for them, and can be time consuming.
Write tests
Tests are used to check the functionality and correctness of APIs on ReactOS compared to Windows implementations. There are also some unit tests that you could help ReactOS pass, which can be found here.
Implement new things
Considering ReactOS is alpha quality software, there is a lot of missing functionality that Windows operating systems have. Before starting a project to implement something, find out if another person is working on the same thing. If you find that someone is already working on it, ask if any assistance is needed for what specifically is being worked on or a related project. Plenty of times a person will start to implement something and never finish before moving to something else. Make sure you stay committed to what you are going to implement, and do not be afraid to ask for assistance if you need help with something.
Patches
A patch is a set of changes to existing source code. The changes in a patch can be merged into existing source code. This process is referred to as applying a patch (to source code). Which changes a patch contains and the way the patch is structured can have significant impact on the consequences that can happen from applying the patch. Below are a few recommendations on how to create and use patches.
Create small patches
Reviewing has proven to be an effective method of discovering bugs, so one should strive towards creating patches that are easy to review. Unfortunately, humans are terrible at tracking large amount of information. Therefore keep the patches as small as possible to make reviewing easier.
Putting only related changes in a patch will make reviewing easier as the reviewer needs to recall less information about the existing source code that is changed.
Notice the risks which are associated with applying the patch
The risk of introducing a bug is higher with some types of changes than others. Formatting is a relatively safe change while semantic changes to complex code is a highly risky change. This means that reviewing a formatting-only patch is not as important as reviewing a patch with semantic changes to complex code (and thus it doesn't hurt so much if a formatting patch is large). When mixing safe and unsafe changes, the overall risk of introducing a bug in a given patch is the same as if the changes were spread over several patches. However, the risk of the individual patch is equal to risk of the most risky change in the patch. So if a 1 line highly risky change is hidden in a 2000 line otherwise safe patch, then the overall risk for the whole patch is highly risky. Therefore strive towards putting changes of similar risk into the same patch.
Set goals for your next patch
To help prevent your patches from becoming too large, set one or more goals for your next patch before you start making any changes. A goal could be to refactor a part of the source code which is hard to understand. It could be to implement part or all of a new feature, or fix a bug that exists in the existing source code. If achieving the goals require too many changes and would make the patch become large and/or contain many unrelated changes, then define new goals which, when reached, would ensure that the original goals would be partially achieved.
Keep focus when developing the patch
While developing a patch, it can be tempting to fix existing issues as you come across them while reading the source code. This can however quickly cause the patch to become large and contain several unrelated changes which have nothing to do with achieving the goals which were defined for the patch. Resist the temptation and put in a note in the source code instead, or (even better) put the issue in the issue tracking system.
Review Patches
Drupal has some tips for reviewing patches.
Places to find information
- MSDN - Your search should start here.
- External Documentation Links - Otherwise you should try to find something here.
- ReactOS Techwiki - Documentation provided or collected by ReactOS developers.
