Working with ESAPI to create a Pull Request (PR) for ESAPI

1. If a GitHub issue does not already exist, create a GitHub issue to work on.

   • If you are an ESAPI GitHub contributor, assign the GitHub issue to yourself, otherwise note in a comment that you want to have it assigned to you.

2. [If you have not already done so] 'fork' the ESAPI/esapi-java-legacy repo to your personal GitHub repo.

3. [If needed], clone your personal forked esapi-java-legacy repo to your local system where you will be working on it. If you have already cloned ESAPI previously, make sure that your local system copy is in sync with the upstream 'develop' branch for ESAPI/esapi-java-legacy.

4. Create a new branch to work on the issue:

   git checkout -b newBranchName

   It is suggested that you might name the branch something like:

    issue-<issue#>
   

   e.g., issue-429

   But that only makes sense if your PR is only going to include a single issue. You can use something like 'issues-385+386' or you can create a branch name that is relevant to the issues that you want to address (e.g., 'logSpecial' for issues 385 and 386), etc. Use your best judgement.

5. Make your changes on your local system and commit your changes. IMPORTANT NOTE: ESAPI now has enabled "branch protection" for the master and develop branches and thus if you want your PR to be merged, you must be doing signed commits.

6. Push your changes to your forked repository (i.e., the 'origin'). E.g.,

   git push origin newBranchName

7. Go back to your personal GitHub repo and create a pull request.

   • Go to your esapi-java-legacy forked repository.
   • Click on the 'Pull Request" button on GitHub for that repo.
   • Pick the branch that you wish to have merged using the "Head branch" dropdown. This will be 'newBranchName' (or obviously, whatever you actually named it.)
   • Enter a title and description for your PR. Somewhere in either the title or description, mention the issue number and in the description, summarize what you've done to fix it.

8. On your local system, merge your changes to your 'develop' branch. E.g., if you made changes on 'newBranchName', then git checkout develop git merge newBranchName While not required, you intend on doing further work on ESAPI from your personal forked GitHub repo, then you probably want to also push your changes from develop. E.g.,

    `git push origin develop`
   

9. Once your PR has been accepted, you can delete that branch on your forked repository if you wish. (Of course, if you haven't merged locally, as per the previous step, you probably will want to do that first.)

You can find additional details in the file 'CONTRIBUTING-TO-ESAPI.txt'