HACKING

$Id$

Nmap HACKING
------------

Information for potential Nmap hackers!

Source is provided to Nmap because we believe users have a
right to know exactly what a program is going to do before they run
it.  This also allows you to audit the software for security holes
(none have been found so far).

Source code also allows you to port Nmap to new platforms, fix bugs,
and add new features.  You are highly encouraged to send your changes
to dev@nmap.org for possible incorporation into the main
distribution.  By sending these changes to Fyodor or one of the
Insecure.Org development mailing lists, it is assumed that you are
offering the Nmap Project (Insecure.Com LLC) unlimited, non-exclusive
right to reuse, modify, and relicense the code.  This is important
because the inability to relicense code has caused devastating
problems for other Free Software projects (such as KDE and NASM).
Nmap will always be available Open Source.  If you wish to specify
special license conditions of your contributions, just say so when you
send them.

Nmap is a community project and has already benefited greatly from
outside contributors (for examples, see the CHANGELOG at
https://nmap.org/changelog.html).  Bugfixes, and portability changes
will almost always be accepted.  Even if you do not have time to track
down and patch a problem, bug reports are always welcome.

Hackers interested in something more major, such as a new feature, are
encouraged to send a mail describing their plans to
dev@nmap.org .  This is a good way to solicit feedback on
your proposals.  List members are often very willing to help.  You
might want to subscribe to that mailing list as well -- send a blank
email to dev-subscribe@nmap.org .  While you are at it, you
might also want to subscribe to announce@nmap.org via the same mechanism.
Web archives of those lists are at http://seclists.org .

Some ideas of useful contributions/projects
-------------------------------------------

Of course, you are welcome to work on whatever suits your fancy.  But
some ideas of contributions that might be particularly useful are listed in
the todo file, available in todo/nmap.txt or online at
https://svn.nmap.org/nmap/todo/nmap.txt

o Bug reports and feature requests at http://issues.nmap.org/ are a good place
  to look for ideas.

o Script ideas page. Writing NSE scripts is an excellent way to contribute to
  the project. You can add your script ideas to our wiki page, or pick one and
  implement it. See: https://secwiki.org/w/Nmap_Script_Ideas

o Nmap GUI improvements -- Zenmap is the Nmap GUI. If you have
  enhancement ideas, give it a shot!  Alternatively, consider
  contributing to the NmapSI and Umit projects available at
  http://www.nmapsi4.org and http://umit.sourceforge.net respectively.
  There are also other satellite projects, with different level of activity,
  such as NmapGUI (http://sourceforge.net/projects/nmapgui) or Nmap::parser
  (http://rubynmap.sourceforge.net).

One of the best ways to help is to join the nmap-dev list
( https://nmap.org/mailman/listinfo/dev ).  Requests for
assistance and new Nmap-related projects are often posted there.

How to make code contributions
------------------------------

The preferred mechanism for submitted changes is unified diffs against
the latest SVN trunk.  Please send them to dev@nmap.org .

Get a local copy of the SVN trunk:

  svn co https://svn.nmap.org/nmap

Make your changes.

Then make a unified diff, by issuing the following command:

  svn diff > nmap.patch

If you've added several features, it's best to send them as several independent
patches if you can.

We also accept Github Pull Requests at https://github.org/nmap/nmap

Style
-----

Code style guidelines and quality checking tools are documented at
https://secwiki.org/w/Nmap/Code_Standards . The short version is:

* Indent with 2 spaces, not tabs
* No trailing whitespace
* Be consistent
* Use comments

Credits
-------

I got the idea for this HACKING file from GNet
(http://www.gnetlibrary.org/) and followed the
general structure of their HACKING file.