diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md new file mode 100644 index 0000000000000000000000000000000000000000..cfe5eff1554aaba813dc5e9e3ee6ef008c0705fc --- /dev/null +++ b/CONTRIBUTING.md @@ -0,0 +1,110 @@ +# How to contribute + +Contributors are essential to Scapy (as they are to most open source +projects). Here is some advice to help you help the project! + +## Project objectives + +We try to keep Scapy as powerful as possible, to support as many +protocols and platforms as possible, to keep and make the code (and +the commit history) as clean as possible. + +Since Scapy can be slow and memory consuming, we try to limit CPU and +memory usage, particularly in parts of the code often called. + +## Reporting issues + +### Questions + +It is OK so submit issues to ask questions (more than OK, +encouraged). There is a label "question" that you can use for that. + +### Bugs + +If you have installed Scapy through a package manager (from your Linux +or BSD system, from PyPI, etc.), please get and install the current +development code, and check that the bug still exists before +submitting an issue. + +Please label your issues "bug". + +If you're not sure whether a behavior is a bug or not, submit an issue +and ask, don't be shy! + +### Enhancements / feature requests + +If you want a feature in Scapy, but cannot implement it yourself or +want some hints on how to do that, open an issue with label +"enhancement". + +Explain if possible the API you would like to have (e.g., give examples +of function calls, packet creations, etc.). + +## Submitting pull requests + +### Coding style & conventions + +First, Scapy "legacy" code contains a lot of code that do not comply +with the following recommendations, but we try to comply with the some +guidelines for new code. + + - The code should be PEP-8 compliant; you can check your code with + [pep8](https://pypi.python.org/pypi/pep8). + - [Pylint](http://www.pylint.org/) can help you write good Python + code (even if respecting Pylint rules is sometimes either too hard + or even undesirable; human brain needed!). + - [Google Python Style Guide](https://google.github.io/styleguide/pyguide.html) + is a nice read! + - Avoid creating unnecessary `list` objects, particularly if they + can be huge (e.g., when possible, use `xrange()` instead of + `range()`, `for line in fdesc` instead of `for line in + fdesc.readlines()`; more generally prefer generators over lists). + +### Tests + +Please consider adding tests for your new features or that trigger the +bug you are fixing. This will prevent a regression from being +unnoticed. + +### New protocols + +New protocols can go either in `scapy/layers` or to +`scapy/contrib`. Protocols in `scapy/layers` should be usually found +on common networks, while protocols in `scapy/contrib` should be +uncommon or specific. + +### Features + +Protocol-related features should be implemented within the same module +as the protocol layers(s) (e.g., `traceroute()` is implemented in +`scapy/layers/inet.py`). + +Other features may be implemented in a module (`scapy/modules`) or a +contribution (`scapy/contrib`). + +### Core + +If you contribute to Scapy's core (e.g., `scapy/base_classes.py`, +`scapy/packet.py`, etc.), please be very careful with performances and +memory footprint, as it is easy to write Python code that wastes +memory or CPU cycles. + +As an example, Packet().__init__() is called each time a **layer** is +parsed from a string (during a network capture or a PCAP file +read). Adding inefficient code here will have a disastrous effect on +Scapy's performances. + +### Code review + +Maintainers tend to be picky, and you might feel frustrated that your +code (which is perfectly working in your use case) is not merged +faster. + +Please don't be offended, and keep in mind that maintainers are +concerned about code maintainability and readability, commit history +(we use the history a lot, for example to find regressions or +understand why certain decisions have been made), performances, +integration in Scapy, API consistency (so that someone who knows how +to use Scapy will know how to use your code), etc. + +**Thanks for reading, happy hacking!** diff --git a/README.md b/README.md index ac6ec859673ead7d09f25e7f0450ca44efffa201..c3203b034e7b0615bed4d42e83d4ceefe3e6448f 100644 --- a/README.md +++ b/README.md @@ -22,6 +22,11 @@ and [the quick demo: an interactive session](http://www.secdev.org/projects/scapy/demo.html) (some examples may be outdated). +# Contributing # + +Want to contribute? Great! Please take a few minutes to +[read this](CONTRIBUTING.md)! + # License # Scapy is free software: you can redistribute it and/or modify it under