The Developer Guide has been updated for the modern security landscape, concentrating less on covering everything in one document and more on introducing a subject/project and then suggesting where more in-depth information can be found. The project has a team of leaders that oversee the project and contributions from members of the security community are positively encouraged.
All contributions and suggestions are certainly welcome, and we ask that you follow the contributing code of conduct. Contributors can make suggestions and provide changes via a pull request.
Feel free to discuss topics in the project wiki and create new discussions.
The Developer Guide does not seek to duplicate the information contained in the many OWASP documentation projects; these projects address their subject fully and completely. Instead the Developer Guide is a starting point on a wide range of subjects which a developer would need to know at least the basics. The Developer Guide should supply this basic knowledge only, and then refer the developer to further reading for more in-depth treatment of the subject. As a rule of thumb, if a section is more than two pages then it is probably too long; split the section up or refer to another more detailed project.
There is a project board which helps to coordinate contributions and keeps track of progress towards each milestone.
- select an issue from the project board for the section you want to work on
- if this issue is free ask for it to be assigned to you
- if the issue has already been assigned then coordinate with the existing owner
- if there is not an existing issue that describes your content then suggest one
- provide your contributed content as a pull request
The Developer Guide will have many contributors, and it is an aim to keep the style of writing similar throughout. Follow the style used in OWASP flagship projects ASVS and WSTG, which is speaking from first person plural and semi-formal in tone.
Generally the guide is aimed at the introductory to medium technical levels, and should rarely deal with any subject at an advanced level. This is a deliberate policy that makes the guide accessible and keeps the length reasonable.
The overview/introduction of the main sections should be aimed at the introductory level, with more detail contained in the sub-sections at a medium technical level. Note this guide should not replicate the many detailed sources on specific security topics; instead provide links to these specialist security knowledge bases.
Each sub-section should deal with one specific subject, for example 'Threat modeling', or a single project such as the OWASP 'Threat Dragon' Builder/Tool project.
Sub-sections that describe an individual project should follow the same structure:
- Introduction, summarising the project at a very high level: supply a couple of sentences on the project including its status as an OWASP project and where to find it
- The 'What', explaining what the project is to a general level: go into more detail about the project so that a developer can gain an overview of what this project can provide for them
- The 'Why', explaining why developers will want to use the project: provide more context for project that allows developers to determine whether to use it in their team
- The 'How', describe how to get started with the project give a brief outline of how the project provides value for a web application development team Do not repeat the project documentation itself; ideally provide a primer and a pointer to the project documentation
- Further reading or resources, if any, providing links on the project at an advanced/detailed level
Note that the page describing a project should not be the same as the project documentation on the OWASP site, the Developer Guide should strive to be a ' TL;DR ' for the project running to one or maybe two pages.
The OWASP projects have media kits that contain biographies of the project leaders and other project media. This can be used for images and marketing material.
The pull requests have checks applied to them:
- Link checker for any broken links; if there is an imperative for a broken link then add it to
.lycheeignore - Markdown lint that ensures the markdown is consistent and valid
- Spell checker; new words that are not recognised can be added to
/.wordlist.txt
if all these checks pass then both the PDF and ePub versions of the guide are provided as github artifacts.
The pipeline will apply checks to all pull-requests, and will fail on any error. To run these checks locally before pushing a commit, run these commands from the top directory:
- Link checker:
lychee --max-retries 5 --exclude-path './_includes/*.html' './**/*.md' - Markdown linter:
markdownlint-cli2 **/*.md - Spell checker:
pyspelling --config .spellcheck.yaml - commands to create PDF and ePub outputs:
tail -n +14 -q $(find draft -name "*[0-9]*.md" | sort) > draft.markdown
pandoc -f markdown -o draft.pdf --resource-path="draft/assets/images:draft/assets:draft" draft/title.pdf.yaml draft.markdown
pandoc -f markdown -o draft.epub --resource-path="draft/assets/images:draft/assets:draft" draft/title.yaml draft.markdown
Follow instructions to install the command line lychee and pandoc.
To install markdownlint-cli2 use npm: npm install markdownlint-cli2 --global,
and to install pyspelling use pip: pip install pyspelling
The release process is automatic, and triggers when the repo is tagged with a version number. To trigger the release this process from within a cloned repo:
- tag the release, for example:
git tag 4.1.1 - push to the repo, for example:
git push origin 4.1.1
The github release workflow then creates the pull request with modifications to the release area promoted from the draft area. Review the changes and, if all are correct, merge the pull request. This will also automatically update the public web document and PDF/e-book versions.
It is good practice to bundle the PDF and ePub files into the release area, using the wording from the previous releases as a guide to the release notes.