Contributing

Contributions are what make the open source community such an amazing place to learn, inspire, and create. Any contributions you make are greatly appreciated.

If you have a suggestion that would make this better, please fork the repo and create a pull request. You can also simply open an issue with the tag "enhancement". Don't forget to give the project a star! Thanks again!

  1. Document your work. See the how to make good documentation chapter.
  2. For each method or object implemented, do not forget to make tests with doctest. See here.
  3. Create Python binding. See this link.
  4. Benchmark your work. See this link.
  5. Create cli interface. See This link.
  6. Open PR.

1-Documentation

The documentation is generated by doctstring with rustdoc. To edit the documentation, go to the code and modify the doctstring after ///.

Then, in order to generate documentation from root folder do:

cargo doc --all --no-deps

Fell free to view your own doc with

cargo doc --open --all --no-deps

This project uses cargo doc.

The documentation is self-generated on each pull request.

To check if the cryptatools documentation has been updated after a merge request, see: the API documentation.

2-Testing

In order to run unit tests, you MUST be in the directory cryptatools-rs. Run unit tests with doctests with the command:

cargo test --all

Unit test are made with doctests.

(back to top)

3-Create Python bindings.

Cryptatools relies on uniffi to provide bindings to Python3. Ensure to provide Python3 bindings before making your Pull Request.

To create Python Bindings, edit the file cryptatools-rs/src/cryptatools.udl. Edit it to add your newly created object as mentionned in the official uniffi documentation at this address: https://mozilla.github.io/uniffi-rs/udl_file_spec.html.

Then do not forget to edit the file cryptatools-rs/cryptatools-core/src/lib.rs and just before the:

uniffi_macros::include_scaffolding!("cryptatools");

This step will generate a single python file that you could import directly. Sadly the good pratice you must do to import these is a bit more complicated.

cryptatools-rs\cryptatools-core\setup.py

In order to import your own crate, create the corresponding python file or folders under cryptatools-rs\cryptatools-core\bindings\python3\cryptatools-core\cryptanalysis\. Here you need to import the necessary objects from from cryptatools_core.python3_bindings. Example, in the file cryptatools-rs\cryptatools-core\bindings\python3\cryptatools-core\cryptography\encryption\monoalphabetic_cipher\caesar_number.py we just have written: from cryptatools_core.python3_bindings import CaesarNumberAlgorithm.

Once this is done, fell free to write unit tests. At least one for each method implemented. The tests are writtenh in the file cryptatools-rs\cryptatools-core\binding-testing\testing.py.

You are now free to test and compile your code with the documentation at this link.

4-Benchmarking

Sometimes, a function could sepnd too much time. In this case, you can debug your specific function from the template in the file benches\cryptatools_benchmark\main.rs.

Then test your function with:

cargo bench

In the current state of cryptatools, it is not mandatory from a pull request to benchmark all the code. But could be considered as a good improvment.

5-Create cli.

Each feature from cryptatools-core will be implemented to the cli in the folder cryptatools-cli. When you will have finish to implement your feature in incryptatools-core and when you have finish your feature in Python bindings, fell free to create the cli of your modifications.

Then test it with:

cargo install --path .\cryptatools-cli\ ;