Difference between revisions of "Developer Guidelines"

From SleuthKitWiki
Jump to: navigation, search
m (Protected "Developer Guidelines" [edit=sysop:move=sysop])
 
(5 intermediate revisions by 2 users not shown)
Line 1: Line 1:
This page contains the guidelines for developing code for The Sleuth Kit and Autopsy.  These guidelines are not about the technical designs of the tools, rather they are about how code is contributed and merged in. Note that this document is a work in progress as the process is officially defined.  
+
This page contains the guidelines for developing code for [[The Sleuth Kit]] and [[Autopsy]].  These guidelines are not about the technical designs of the tools, rather they are about how code is contributed and merged in. Note that this document is a work in progress as the process is officially defined.  
  
 
= Communications =
 
= Communications =
 
The [http://lists.sourceforge.net/lists/listinfo/sleuthkit-developers Sleuth Kit Developers] e-mail list is the official communication forum for TSK and Autopsy development. Subscribe to participate in the development process.  
 
The [http://lists.sourceforge.net/lists/listinfo/sleuthkit-developers Sleuth Kit Developers] e-mail list is the official communication forum for TSK and Autopsy development. Subscribe to participate in the development process.  
  
= Submitting Patches / Code =
+
There are also [[trackers]] on SourceForge and github to keep track of bugs and feature requests.  
To contribute code or patches to the project, send e-mail to the [http://lists.sourceforge.net/lists/listinfo/sleuthkit-developers Sleuth Kit Developers] list. Include the new code or diffs of the changes. Code submissions should follow the error handling, Unicode, and other conventions of the specific tool.  A more detailed list of tool-specific guidelines is being developed.
+
  
To make diffs of the changes, run the following command on a Unix system (or from cygwin on Windows):
 
  
<code>
+
= Source Code Branches =
% diff -Nru sleuthkit-old sleuthkit-new > changes.patch
+
We are currently using a branching model based on [http://nvie.com/posts/a-successful-git-branching-model/ gitflow].  We have thoughts about using a variation of this in the near future, but it is basically what we are doing now.  You can find a cheatsheet on the [[git workflow]] page.
</code>
+
 
 +
The basic take away of it is:
 +
* master branch is the last stable release
 +
* develop branch is where development is going on
 +
 
 +
Our thought is to make some slight variations on this, namely that:
 +
* the develop branch will be called something like 'develop-X.Y' that signals the version that is being developed on that branch.
 +
 
 +
 
 +
= Submitting Patches / Code =
 +
All of the development is now done from our [http://www.github.com/sleuthkit/ github] projects.  To submit code to one of the projects, you will need to create a [http://help.github.com/articles/using-pull-requests pull request].  The previously linked to page outlines how to generate a pull request, but the high-level overview is to:
 +
* Create a github account
 +
* Create a fork of sleuthkit, Autopsy, or another project into your account
 +
* Clone the forked repo.
 +
* Change to the develop branch
 +
<code>git checkout develop</code>
 +
* Create a branch based on the develop branch for the feature that you want to develop (i.e. a feature branch)
 +
<code>git checkout -b feature_name</code>
 +
* Make changes to the code in that branch and commit them
 +
* Push that branch to your fork on github.com
 +
<code>git push origin feature_name</code>
 +
* Create a pull request for the feature branch to the develop branch.  Review the diff to make sure it is what you want. By default, it will be against the master branch and not develop.
  
 
The patches and code contributions will be reviewed and incorporated into the main development if they are approved. It is also helpful to submit test images and test cases that can be used to test the new code.  
 
The patches and code contributions will be reviewed and incorporated into the main development if they are approved. It is also helpful to submit test images and test cases that can be used to test the new code.  
 +
 +
Code submissions should follow the error handling, Unicode, and other conventions of the specific tool.  A more detailed list of tool-specific guidelines is being developed.
 +
  
 
= Code Acceptance =
 
= Code Acceptance =
 
Currently, these tools have a [http://producingoss.com/html-chunk/social-infrastructure.html#benevolent-dictator Benevolent Dictator] model for incorporating code into the official distribution.  As more developers get involved, this can change. Acceptance is based on code quality and completeness.
 
Currently, these tools have a [http://producingoss.com/html-chunk/social-infrastructure.html#benevolent-dictator Benevolent Dictator] model for incorporating code into the official distribution.  As more developers get involved, this can change. Acceptance is based on code quality and completeness.

Latest revision as of 12:35, 11 August 2014

This page contains the guidelines for developing code for The Sleuth Kit and Autopsy. These guidelines are not about the technical designs of the tools, rather they are about how code is contributed and merged in. Note that this document is a work in progress as the process is officially defined.

Communications

The Sleuth Kit Developers e-mail list is the official communication forum for TSK and Autopsy development. Subscribe to participate in the development process.

There are also trackers on SourceForge and github to keep track of bugs and feature requests.


Source Code Branches

We are currently using a branching model based on gitflow. We have thoughts about using a variation of this in the near future, but it is basically what we are doing now. You can find a cheatsheet on the git workflow page.

The basic take away of it is:

  • master branch is the last stable release
  • develop branch is where development is going on

Our thought is to make some slight variations on this, namely that:

  • the develop branch will be called something like 'develop-X.Y' that signals the version that is being developed on that branch.


Submitting Patches / Code

All of the development is now done from our github projects. To submit code to one of the projects, you will need to create a pull request. The previously linked to page outlines how to generate a pull request, but the high-level overview is to:

  • Create a github account
  • Create a fork of sleuthkit, Autopsy, or another project into your account
  • Clone the forked repo.
  • Change to the develop branch

git checkout develop

  • Create a branch based on the develop branch for the feature that you want to develop (i.e. a feature branch)

git checkout -b feature_name

  • Make changes to the code in that branch and commit them
  • Push that branch to your fork on github.com

git push origin feature_name

  • Create a pull request for the feature branch to the develop branch. Review the diff to make sure it is what you want. By default, it will be against the master branch and not develop.

The patches and code contributions will be reviewed and incorporated into the main development if they are approved. It is also helpful to submit test images and test cases that can be used to test the new code.

Code submissions should follow the error handling, Unicode, and other conventions of the specific tool. A more detailed list of tool-specific guidelines is being developed.


Code Acceptance

Currently, these tools have a Benevolent Dictator model for incorporating code into the official distribution. As more developers get involved, this can change. Acceptance is based on code quality and completeness.