Skip to content

Commit 08f52e7

Browse files
kwwallkwwall
committed
Initial commit for Markdown version of 'CONTRIBUTING-TO-ESAPI.txt'.
1 parent 807820e commit 08f52e7

File tree

1 file changed

+118
-0
lines changed

1 file changed

+118
-0
lines changed

‎CONTRIBUTING.md

Lines changed: 118 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,118 @@
1+
# Contributing to ESAPI -- Details
2+
3+
## Getting Started
4+
If you have not already done so, go back and read the section
5+
"[Contributing to ESAPI legacy](https://github.com/ESAPI/esapi-java-legacy/blob/develop/README.md#contributing-to-esapi-legacy)" in ESAPI's README.md file. It
6+
may contain updates and advice not contained herein.
7+
8+
### A Special Note on GitHub Authentication
9+
GitHub has announced that they are deprecating password based authentication
10+
using username / password and beginning 2021-08-13, you will no longer be
11+
able to your password to authenticate to 'git' operations on GitHub.com.
12+
Please see https://github.blog/2020-12-15-token-authentication-requirements-for-git-operations/
13+
for details and plan accordingly.
14+
15+
### A Special Note Regarding Making Commits for PRs
16+
Shortly after the 2.5.1.0 ESAPI release in late November 2022, the ESAPI
17+
team decided to lock down the 'develop' amd 'main' branches. Merges from
18+
PRs are done to the 'develop' branch. That means that if you intend to
19+
contribute to ESAPI, you must be signing your commits. Please see the
20+
GitHub instructions at
21+
https://docs.github.com/en/authentication/managing-commit-signature-verification/signing-commits
22+
for details.
23+
24+
### Git Branching Model
25+
We are following the branching model described in
26+
https://nvie.com/posts/a-successful-git-branching-model
27+
If you are unfamiliar with it, you would be advised to give it a quick
28+
perusal. The major point is that the 'main' (formerly 'master') branch is
29+
reserved for official releases (which will be tagged), the 'develop' branch
30+
is used for ongoing development work and is the default branch, and we
31+
generally work off 'issue' branches named 'issue-#' where # is the GitHub
32+
issue number. (The last is not an absolute requirement, but rather a
33+
suggested approach.)
34+
35+
Finally, we recommend setting the git property 'core.autocrlf' to 'input'
36+
in your $HOME/.gitconfig file; e.g., that file should contain something
37+
like this:
38+
39+
[core]
40+
autocrlf = input
41+
42+
43+
### Required Software
44+
We use Maven for building. Maven 3.6.3 or later is required. You also need
45+
JDK 8 or later. [Note: If you use JDK 9 or later, there will be multiple
46+
failures when you try to run 'mvn test' as well as some general warnings.
47+
See [ESAPI GitHub issue #496](https://github.com/ESAPI/esapi-java-legacy/issues/496) for details. We welcome volunteers to address
48+
this.]
49+
## Finding Something Interesting to Work on
50+
51+
See the section [Contributing to ESAPI Legacy](https://github.com/ESAPI/esapi-java-legacy/blob/develop/README.md#contributing-to-esapi-legacy)
52+
in the ESAPI README for suggestions. While you don't *have* to work on something labeled "good first issue"
53+
or "help wanted", those are good places to start for someone not yet familiar with the ESAPI code base.
54+
55+
You will need a account on GitHub though. Once you create one, let us know
56+
what it is. Then if you want to work on a particular issue, we can assign
57+
it to you so someone else won't take it.
58+
59+
If you have questions, email Kevin Wall ([email protected]) or Matt
60+
Seil ([email protected]).
61+
62+
63+
## Building ESAPI
64+
See our local GitHub wiki page, [Building ESAPI](https://github.com/ESAPI/esapi-java-legacy/wiki/Building-ESAPI),
65+
which briefly discusses how to build ESAPI via Maven.
66+
67+
You can also refer to [Using ESAPI for Java with Eclipse](https://github.com/ESAPI/esapi-java-legacy/wiki/Using-ESAPI-for-Java-with-Eclipse)
68+
if you prefer working from IDEs. There is also a much older ESAPI wiki page,
69+
[Building with Eclipse](https://www.owasp.org/index.php/ESAPI-BuildingWithEclipse)
70+
that might be useful.
71+
72+
As always, any contributions to ESAPI's admittedly skimpy documentation in this area is welcome.
73+
In particular, contributing some hints about debugging applications using ESAPI
74+
would be very useful to our ESAPI clients.
75+
76+
## Steps to work with ESAPI
77+
I usually do everything from the bash command prompt in Linux Mint,
78+
but other people use Windows. If you prefer an IDE, I can't help you
79+
much, but I can help with at least modest problems. If you have more
80+
difficult problems, I will probably refer you to my project co-leader,
81+
Matt who groks git a lot better than I.
82+
83+
But the basic high level steps are:
84+
85+
1. Fork https://github.com/ESAPI/esapi-java-legacy to your own GitHub repository using the GitHub web site.
86+
2. On your local laptop, clone your own GitHub ESAPI repo (i.e, the forked repo created in previous step)
87+
3. Create a new branch to work on an issue. I usually name the branch 'issue-#' where '#' is the GitHub issue # is will be working on, but you can call it whatever. E.g.,
88+
```bash
89+
$ git checkout -b issue-#
90+
```
91+
4. Work on the GitHub issue on this newly created issue-# branch. Be sure that you also create new JUnit tests as required that confirm that the issue is corrected, or if you are introducing new functionality, ensure
92+
that functionality is sufficiently covered.
93+
5. Make sure everything builds correctly and all the JUnit tests pass ('mvn test'). [Note: There are some known issues with test failures if your are running under Windows and your local ESAPI Git repo located anywhere other than the C: drive, where the test `ValidatorTest.testIsValidDirectoryPath()` fails.
94+
6. If you have added any dependencies, please also run OWASP Dependency-Check and look at the generated report left in 'target/dependency-check-report.html' to make sure there were not any CVEs introduced. (Alternately you can run 'mvn verify' which will first run the tests and then run Dependency-Check.) Note if this is the first time you have run Dependency-Check for ESAPI, expect it to take a while (often 30 minutes or so!). To execute Dependency Check from Maven, run:
95+
```bash
96+
$ mvn org.owasp:dependency-check-maven:check
97+
```
98+
7. Commit your changes locally.
99+
8. Push your 'issue-#' branch to your personal, forked ESAPI GitHub repo. E.g.,
100+
```bash
101+
$ git checkout issue-444
102+
$ git remote -v | grep origin # Confirm 'origin' refers to YOUR PERSONAL GitHub repo
103+
$ git push origin issue-444 # Push the committed changes on the 'issue-444' branch
104+
```
105+
9. Go to your personal, forked ESAPI GitHub repo (web interface) and create a 'Pull Request' (PR) from your 'issue-#' branch.
106+
10. Back on your local personal laptop / desktop, merge your issue branch with your local 'develop' branch. I.e.,
107+
$ git checkout develop
108+
$ git merge issue-444
109+
11. Do not remove your branch on your forked repository until your PR from your branch has been merged into the ESAPI/esapi-java/legacy 'develop' branch.
110+
Note at least one the 3 main contributors on will review your commits before
111+
merging them and they may do a formal code review and request further changes.
112+
Once they are satisfied, they will merge your PR.
113+
114+
In theory, you can do all this 'git' magic from Eclipse and presumably other
115+
IDEs like Oracle NetBeans or JetBrains IntelliJ IDEA. From Eclipse, it is right-click
116+
on the project and then select 'Team' to do the commits, etc. If you choose that
117+
route, you're pretty much on your own because none of us use that for Git
118+
interactions.

0 commit comments

Comments
 (0)