Skip to content

Latest commit

 

History

History
313 lines (222 loc) · 12.5 KB

CONTRIBUTING.md

File metadata and controls

313 lines (222 loc) · 12.5 KB
Raw

Contributor's guide

First of all, thank you for contributing! Please follow these steps to contribute:

  1. Find an issue that needs assistance by searching for the Help Wanted tag
  2. Let us know you're working on it by posting a comment on the issue
  3. Follow the Contribution guidelines to start working on the issue

Remember to feel free to ask for help by leaving a comment within the Issue.

Working on your first pull request? You can learn how from this free series How to Contribute to an Open Source Project on GitHub.

If you've found a bug that is not on the board, follow these steps.

Contribution guidelines

Forking the project

Setting up your system

  1. Install your favorite git client
  2. Create a parent projects directory on your system. For this guide, it will be assumed that it is ~/projects.

Forking feroxbuster

  1. Go to the top-level feroxbuster repository: https://github.com/epi052/feroxbuster
  2. Click the "Fork" button in the upper right hand corner of the interface (more details here)
  3. After the repository has been forked, you will be taken to your copy of the feroxbuster repo at your_username/feroxbuster

Cloning your fork

  1. Open a terminal / command line / Bash shell in your projects directory (e.g.: ~/projects/)
  2. Clone your fork of feroxbuster, making sure to replace your_username with your GitHub username. This will download the entire feroxbuster repo to your projects directory.
$ git clone https://github.com/your_username/feroxbuster.git

Set up your upstream

  1. Change directory to the new feroxbuster directory (cd feroxbuster)
  2. Add a remote to the official feroxbuster repo:
$ git remote add upstream https://github.com/epi052/feroxbuster.git

Now you have a local copy of the feroxbuster repo!

Maintaining your fork

Now that you have a copy of your fork, there is work you will need to do to keep it current.

Rebasing from upstream

Do this prior to every time you create a branch for a PR:

  1. Make sure you are on the main branch
$ git status
On branch main
Your branch is up-to-date with 'origin/main'.

If your aren't on main, resolve outstanding files and commits and checkout the main branch

$ git checkout main
  1. Do a pull with rebase against upstream
$ git pull --rebase upstream main

This will pull down all of the changes to the official main branch, without making an additional commit in your local repo.

  1. (Optional) Force push your updated main branch to your GitHub fork
$ git push origin main --force

This will overwrite the main branch of your fork.

Creating a branch

Before you start working, you will need to create a separate branch specific to the issue or feature you're working on. You will push your work to this branch.

Naming your branch

Name the branch something like 23-xxx where xxx is a short description of the changes or feature you are attempting to add and 23 corresponds to the Issue you're working on.

Adding your branch

To create a branch on your local machine (and switch to this branch):

$ git checkout -b [name_of_your_new_branch]

and to push to GitHub:

$ git push origin [name_of_your_new_branch]
If you need more help with branching, take a look at this.

Setting up for feroxbuster development

For doing feroxbuster development, all you really need is rust installed on your system (I'll leave the choice of IDE to you, but VS Code and JetBrains both have very nice rust plugins).

Install rustup

The primary way that folks install Rust is through a tool called Rustup, which is a Rust installer and version management tool.

curl --proto '=https' --tlsv1.2 -sSf https://sh.rustup.rs | sh
rustup update

After running the two commands above, you should be able to run cargo.

$> cargo --version
cargo 1.45.0 (744bd1fbb 2020-06-15)

Making changes

It's your time to shine!

How to find code in the feroxbuster codebase to fix/edit

The feroxbuster project directory structure is pretty simple and straightforward. All actual code for feroxbuster is located underneath the src directory. Integration tests are in the tests directory. There are various other files in the root directory, but these are primarily related to continuous integration and release deployment.

Static code analysis

feroxbuster uses the clippy code linter.

The command that will ultimately be used in the CI pipeline for linting is cargo clippy --all-targets --all-features -- -D warnings -A clippy::mutex-atomic.

Before submitting a Pull Request, the above command should be run. Please do not ignore any linting errors in code you write or modify, as they are meant to help by ensuring a clean and simple code base.

Running the test suite

When you're ready to share your code, run the test suite:

$ cd ~/projects/feroxbuster
$ cargo test

and ensure all tests pass.

Test coverage can be checked using grcov. Installation and execution are summarized below.

cargo install grcov
rustup install nightly
rustup default nightly
export CARGO_INCREMENTAL=0
export RUSTFLAGS="-Zprofile -Ccodegen-units=1 -Copt-level=0 -Clink-dead-code -Coverflow-checks=off -Zpanic_abort_tests -Cpanic=abort"
export RUSTDOCFLAGS="-Cpanic=abort"
cargo build
cargo test
grcov ./target/debug/ -s . -t html --llvm --branch --ignore-not-existing -o ./target/debug/coverage/
firefox target/debug/coverage/index.html

Squashing your commits

When you make a pull request, it is preferable for all of your changes to be in one commit. Github has made it very simple to squash commits now as it's available through the web interface at pull request submission time.

Creating a pull request

What is a pull request?

A pull request (PR) is a method of submitting proposed changes to the feroxbuster repo (or any repo, for that matter). You will make changes to copies of the files which make up feroxbuster in a personal fork, then apply to have them accepted by the feroxbuster team.

Need help?

GitHub has a good guide on how to contribute to open source here.

Editing via your local fork
  1. Perform the maintenance step of rebasing main
  2. Ensure you're on the main branch using git status:
$ git status
On branch main
Your branch is up-to-date with 'origin/main'.

nothing to commit, working directory clean
  1. If you're not on main or your working directory is not clean, resolve any outstanding files/commits and checkout main git checkout main
  2. Create a branch off of main with git: git checkout -B branch/name-here
  3. Edit your file(s) locally with the editor of your choice
  4. Check your git status to see unstaged files
  5. Add your edited files: git add path/to/filename.ext You can also do: git add . to add all unstaged files. Take care, though, because you can accidentally add files you don't want added. Review your git status first.
  6. Commit your edits: git commit -m "Brief description of commit".
  7. Squash your commits, if there are more than one
  8. Push your commits to your GitHub Fork: git push -u origin branch/name-here
  9. Once the edits have been committed, you will be prompted to create a pull request on your fork's GitHub page
  10. By default, all pull requests should be against the main branch
  11. Submit a pull request from your branch to feroxbuster's main branch
  12. The title (also called the subject) of your PR should be descriptive of your changes and succinctly indicate what is being fixed - Examples: Add test cases for Unicode support; Correct typo in overview documentation
  13. In the body of your PR include a more detailed summary of the changes you made and why - If the PR is meant to fix an existing bug/issue, then, at the end of your PR's description, append the keyword closes and #xxxx (where xxxx is the issue number). Example: closes #1337. This tells GitHub to close the existing issue if the PR is merged.
  14. Creating the PR causes our continuous integration (CI) systems to automatically run all of the unit tests on all supported OSes. You should watch your PR to make sure that all unit tests pass.
  15. If any unit tests fail, you should look at the details and fix the failures. You can then push the fix to the same branch in your fork. The PR will automatically get updated and the CI system will automatically run all of the unit tests again.

How we review and merge pull requests

  1. If your changes can merge without conflicts and all unit tests pass, then your pull request (PR) will have a big green checkbox which says something like "All Checks Passed" next to it. If this is not the case, there will be a link you can click on to get details regarding what the problem is. It is your responsibility to make sure all unit tests are passing. Generally a Maintainer will not QA a pull request unless it can merge without conflicts and all unit tests pass.

  2. If a Maintainer reviews a pull request and confirms that the new code does what it is supposed to do without seeming to introduce any new bugs, and doesn't present any backward compatibility issues, they will merge the pull request.

Next steps

If your PR is accepted

Once your PR is accepted, you may delete the branch you created to submit it. This keeps your working fork clean.

You can do this with a press of a button on the GitHub PR interface. You can delete the local copy of the branch with: git branch -D branch/to-delete-name

If your PR is rejected

Don't worry! You will receive solid feedback from the Maintainers as to why it was rejected and what changes are needed.

Many pull requests, especially first pull requests, require correction or updating.

If you have a local copy of the repo, you can make the requested changes and amend your commit with: git commit --amend This will update your existing commit. When you push it to your fork you will need to do a force push to overwrite your old commit: git push --force

Be sure to post in the PR conversation that you have made the requested changes.

Other resources

Advice

Here is some advice regarding what makes a good pull request (PR) from our perspective:

  • Multiple smaller PRs divided by topic are better than a single large PR containing a bunch of unrelated changes
  • Good unit/functional tests are very important
  • Accurate documentation is also important
  • It's best to create a dedicated branch for a PR, use it only for that PR, and delete it once the PR has been merged
  • It's good if the branch name is related to the PR contents, even if it's just "fix123" or "add_more_tests"
  • Code coverage of the unit tests matters, so try not to decrease it
  • Think twice before adding dependencies to third-party libraries because it could affect a lot of users

Acknowledgement

Thanks to the awesome guys at cmd2 for their fantastic CONTRIBUTING file from which we have borrowed heavily.