Contributing

All contributions are welcomed, thank you for taking the time to contribute to this project! These are a set of guidelines for contributing to the development of Slips [1].

How can you contribute?

  • Run Slips and report bugs and needed features, and suggest ideas

  • Pull requests with a solved GitHub issue and new feature

  • Pull request with a new detection module.

Persistent Git Branches

The following git branches in the Slips repository are permanent:

  • master: contains the stable version of Slips, with new versions at least once a month.

  • develop: contains the latest unstable version of Slips and also its latest features. All new features should be based on this branch.

Naming Git branches for Pull Requests

To keep the Git history clean and facilitate the revision of contributions we ask all branches to follow concise namings. These are the branch-naming patterns to follow when contributing to Slips:

  • author-bugfix-: pull request branch, contains one bugfix,

  • author-docs-: pull request branch, contains documentation work,

  • author-enhance-: pull request branch, contains one enhancement (not a new feature, but improvement nonetheless)

  • author-feature-: pull request branch, contains a new feature,

  • author-refactor-: pull request branch, contains code refactoring,

What branch should you base your contribution to Slips?

As a general rule, base your contributions to the develop branch.

Creating a pull request

Commits:

  • Commits should follow the KISS principle: do one thing, and do it well (keep it simple, stupid).

  • Commit messages should be easily readable, imperative style (”Fix memory leak in…”, not “FixES mem…”)

Pull Requests:

  • If you have developed multiple features and/or bugfixes, create separate branches for each one of them, and request merges for each branch;

  • Each PR to develop will trigger the develop Github checks, these checks will run Slips unit tests and integration tests locally in a ubuntu VM and in docker to make sure the branch is ready to merge.

  • PRs won’t be merged unless the checks pass.

  • The cleaner you code/change/changeset is, the faster it will be merged.

Beginner tips on how to create a PR in Slips

Here’s a very simple beginner-level steps on how to create your PR in Slips

  1. Fork the Slips repo

  2. Clone the forked repo

  3. In your clone, checkout origin/develop: git checkout origin develop

  4. Install slips pre-commit hooks pre-commit install

  5. Generate a baseline for detecting secrets before they’re committed detect-secrets scan --exclude-files ".*dataset/.*|(?x)(^config/local_ti_files/own_malicious_JA3.csv$|.*test.*|.*\.md$)" > .secrets.baseline

  6. Create your own branch off develop using your name and the feature name: git checkout -b <yourname>_<feature_name> develop

  7. Change the code, add the feature or fix the bug, etc. then commit with a descriptive msg git commit -m "descriptive msg here"

  8. Test your code: this is a very important step. you shouldn’t open a PR with code that is not working: ./tests/run_all_tests.sh

  9. If some tests didn’t pass, it means you need to fix something in your branch.

  10. Push to your own repo: git push -u origin <yourname>_<feature_name>

  11. Open a PR in Slips, remember to set the base branch as develop.

  12. List your changes in the PR description

Rejected PRs

We will not review PRs that have the following:

  • Code that’s not tested. a screenshot of the passed tests is required for each PR.

  • PRs without steps to reproduce your proposed changes.

  • Asking for a step by step guide on how to solve the problem. It is ok to ask us clarifications after putting some effort into reading the code and the docs. but asking how exactly should i do X shows that you didn’t look at the code

Some IDEs like PyCharm and vscode have the option to open a PR from within the IDE.

That’s it, now you have a ready-to-merge PR!

[1] These contributions guidelines are inspired by the project Snoopy