diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md new file mode 100644 index 0000000..aae374e --- /dev/null +++ b/CONTRIBUTING.md @@ -0,0 +1,155 @@ +# Contribution guide + +First, thank you for contributing! We love and encourage pull requests from +everyone. Please follow the guidelines: + +- Check the open [issues](https://github.com/TrueCloudLab/tzhash/issues) and + [pull requests](https://github.com/TrueCloudLab/tzhash/pulls) for existing + discussions. + +- Open an issue first, to discuss a new feature or enhancement. + +- Write tests, and make sure the test suite passes locally and on CI. + +- Open a pull request, and reference the relevant issue(s). + +- Make sure your commits are logically separated and have good comments + explaining the details of your change. + +- After receiving feedback, amend your commits or add new ones as + appropriate. + +- **Have fun!** + +## Development Workflow + +Start by forking the `tzhash` repository, make changes in a branch and then +send a pull request. We encourage pull requests to discuss code changes. Here +are the steps in details: + +### Set up your GitHub Repository +Fork [TZHash upstream](https://github.com/TrueCloudLab/tzhash/fork) source +repository to your own personal repository. Copy the URL of your fork (you will +need it for the `git clone` command below). + +```sh +$ git clone https://github.com/TrueCloudLab/tzhash +``` + +### Set up git remote as ``upstream`` +```sh +$ cd tzhash +$ git remote add upstream https://github.com/TrueCloudLab/tzhash +$ git fetch upstream +$ git merge upstream/master +... +``` + +### Create your feature branch +Before making code changes, make sure you create a separate branch for these +changes. Maybe you will find it convenient to name branch in +`/-` format. + +``` +$ git checkout -b feature/123-something_awesome +``` + +### Test your changes +After your code changes, make sure + +- To add test cases for the new code. +- To squash your commits into a single commit or a series of logically separated + commits run `git rebase -i`. It's okay to force update your pull request. +- To run `make test` and `make all` completes. + +### Commit changes +After verification, commit your changes. This is a [great +post](https://chris.beams.io/posts/git-commit/) on how to write useful commit +messages. Try following this template: + +``` +[#Issue] Summary + +Description + + + + +``` + +``` +$ git commit -sam '[#123] Add some feature' +``` + +### Push to the branch +Push your locally committed changes to the remote origin (your fork) +``` +$ git push origin feature/123-something_awesome +``` + +### Create a Pull Request +Pull requests can be created via GitHub. Refer to [this +document](https://help.github.com/articles/creating-a-pull-request/) for +detailed steps on how to create a pull request. After a Pull Request gets peer +reviewed and approved, it will be merged. + +## DCO Sign off + +All authors to the project retain copyright to their work. However, to ensure +that they are only submitting work that they have rights to, we are requiring +everyone to acknowledge this by signing their work. + +Any copyright notices in this repository should specify the authors as "the +contributors". + +To sign your work, just add a line like this at the end of your commit message: + +``` +Signed-off-by: Samii Sakisaka + +``` + +This can easily be done with the `--signoff` option to `git commit`. + +By doing this you state that you can certify the following (from [The Developer +Certificate of Origin](https://developercertificate.org/)): + +``` +Developer Certificate of Origin +Version 1.1 + +Copyright (C) 2004, 2006 The Linux Foundation and its contributors. +1 Letterman Drive +Suite D4700 +San Francisco, CA, 94129 + +Everyone is permitted to copy and distribute verbatim copies of this +license document, but changing it is not allowed. + + +Developer's Certificate of Origin 1.1 + +By making a contribution to this project, I certify that: + +(a) The contribution was created in whole or in part by me and I + have the right to submit it under the open source license + indicated in the file; or + +(b) The contribution is based upon previous work that, to the best + of my knowledge, is covered under an appropriate open source + license and I have the right under that license to submit that + work with modifications, whether created in whole or in part + by me, under the same open source license (unless I am + permitted to submit under a different license), as indicated + in the file; or + +(c) The contribution was provided directly to me by some other + person who certified (a), (b) or (c) and I have not modified + it. + +(d) I understand and agree that this project and the contribution + are public and that a record of the contribution (including all + personal information I submit with it, including my sign-off) is + maintained indefinitely and may be redistributed consistent with + this project or the open source license(s) involved. +``` diff --git a/README.md b/README.md index 055fdaf..82efb02 100644 --- a/README.md +++ b/README.md @@ -5,26 +5,30 @@ **In project root:** ```bash -# show help -make -# run auto demo -make auto +$ make +... +$ ./demo.sh + ``` # Homomorphic hashing in golang -Package `tz` containts pure-Go implementation of hashing function described by Tillich and Źemor in [1] . +Package `tz` contains pure-Go (with some Assembly) implementation of hashing +function described by [Tillich and +Zémor](https://link.springer.com/content/pdf/10.1007/3-540-48658-5_5.pdf). -There are existing implementations already (e.g. [2]), however they are written in C. +There are [existing implementations](https://github.com/srijs/hwsl2-core) +already, however they are written in C. Package `gf127` contains arithmetic in `GF(2^127)` with `x^127+x^63+1` as reduction polynomial. # Description -It can be used instead of Merkle-tree for data-validation, because homomorphic hashes -are concatenable: hash sum of data can be calculated based on hashes of chunks. +TZ Hash can be used instead of Merkle-tree for data-validation, because +homomorphic hashes are concatenable: hash sum of data can be calculated based on +hashes of chunks. -The example of how it works can be seen in tests. +The example of how it works can be seen in tests and demo. # Benchmarks @@ -40,27 +44,30 @@ BenchmarkSum/PureGo_digest-8 68 17795480 ns/op 5.62 MB/ # Contributing -At this moment, we do not accept contributions. Follow us. +Feel free to contribute to this project after reading the [contributing +guidelines](CONTRIBUTING.md). + +Before starting to work on a certain topic, create a new issue first, describing +the feature/topic you are going to implement. # Makefile -``` -→ make +``` bash Usage: make Targets: - attach Attach to existing container - auto Auto Tillich-Zémor hasher demo - down Stop demo container - help Show this help prompt - up Run Tillich-Zémor hasher demo + all Just `make` will build all possible binaries + clean Print version + dep Pull go dependencies + help Show this help prompt + test Run Unit Test with go test + version Print version ``` -# Links +# References -[1] https://link.springer.com/content/pdf/10.1007/3-540-48658-5_5.pdf - -[2] https://github.com/srijs/hwsl2-core \ No newline at end of file +- [https://link.springer.com/content/pdf/10.1007/3-540-48658-5_5.pdf](https://link.springer.com/content/pdf/10.1007/3-540-48658-5_5.pdf) +- [https://github.com/srijs/hwsl2-core](https://github.com/srijs/hwsl2-core)