diff --git a/BUILDING.md b/BUILDING.md new file mode 100644 index 00000000..d07fdaf9 --- /dev/null +++ b/BUILDING.md @@ -0,0 +1,58 @@ +# Jitsuin Archivist Client Development + +## Pre-requisites + +Required tools for this repo are task-runner and docker-ce. + +Install task runner: https://github.com/go-task/task +Install docker-ce: https://docs.docker.com/get-docker/ + +## Workflow + +To see what options are available simply execute: + +```bash +task +``` + +All development is done using a docker image. To create the image execute +the following command. This command only has to be repeated if requirements.txt +or requirements-dev.txt change. + +Dependencies are defined in requirements.txt for the archivist package and +requirements-dev.txt for the tools used to build, test and publish the +archivist package. + +To build the docker builder image: +```bash +task builder +``` + +Make a change to the code and validate the changes: + +```bash +task check +``` + +If ok run the unittests: + +```bash +task unittests +``` + +If 100% coverage and no test failures generate the wheel: + +```bash +task wheel +``` + +Lastly to publish the package to PyPi: + +```bash +task publish +``` + +Note that this requires credentials and will only normally be done by a Jitsuin +representative. + + diff --git a/CODE_OF_CONDUCT.md b/CODE_OF_CONDUCT.md new file mode 100644 index 00000000..37553e89 --- /dev/null +++ b/CODE_OF_CONDUCT.md @@ -0,0 +1,40 @@ +Jitsuin observes the [CNCF Community Code of Conduct](https://github.com/cncf/foundation/blob/master/code-of-conduct.md), reproduced below for emphasis. + +### Contributor Code of Conduct + +As contributors and maintainers of this project, and in the interest of fostering +an open and welcoming community, we pledge to respect all people who contribute +through reporting issues, posting feature requests, updating documentation, +submitting pull requests or patches, and other activities. + +We are committed to making participation in this project a harassment-free experience for +everyone, regardless of level of experience, gender, gender identity and expression, +sexual orientation, disability, personal appearance, body size, race, ethnicity, age, +religion, or nationality. + +Examples of unacceptable behavior by participants include: + +* The use of sexualized language or imagery +* Personal attacks +* Trolling or insulting/derogatory comments +* Public or private harassment +* Publishing others' private information, such as physical or electronic addresses, + without explicit permission +* Other unethical or unprofessional conduct. + +Project maintainers have the right and responsibility to remove, edit, or reject +comments, commits, code, wiki edits, issues, and other contributions that are not +aligned to this Code of Conduct. By adopting this Code of Conduct, project maintainers +commit themselves to fairly and consistently applying these principles to every aspect +of managing this project. Project maintainers who do not follow or enforce the Code of +Conduct may be permanently removed from the project team. + +This code of conduct applies both within project spaces and in public spaces +when an individual is representing the project or its community. + +Instances of abusive, harassing, or otherwise unacceptable behavior may be reported by contacting a Jitsuin administrator on . + +This Code of Conduct is adapted from the Contributor Covenant +(http://contributor-covenant.org), version 1.2.0, available at +http://contributor-covenant.org/version/1/2/0/ + diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md new file mode 100644 index 00000000..131d97b4 --- /dev/null +++ b/CONTRIBUTING.md @@ -0,0 +1,99 @@ +# Contributing to jitsuin-archivist # + +Thanks for taking the time to contribute to jitsuin-archivist! + +Contributing is not limited to writing code and submitting a PR. Feel free to submit an +[issue](https://github.com/jitsuin-inc/archivist-python/issues/new/choose) or comment on an existing one +to report a bug, provide feedback, or suggest a new feature. + +Of course, contributing code is more than welcome! To keep things simple, if you're fixing a small issue, +you can simply submit a PR and we will pick it up. However, if you're planning to submit a bigger PR to implement +a new feature or fix a relatively complex bug, please open an issue that explains the change and the motivation for it. +If you're addressing a bug, please explain how to reproduce it. + +## Pull request and git commit guidance + +### Opening PRs and organizing commits +PRs should generally address only 1 issue at a time. If you need to fix two bugs, open two separate PRs. +This will keep the scope of your pull requests smaller and allow them to be reviewed and merged more quickly. + +When possible, fill out as much detail in the pull request template as is reasonable. +Most important is to reference the GitHub issue that you are addressing with the PR. + +**NOTE:** GitHub has +[a feature](https://docs.github.com/en/github/managing-your-work-on-github/linking-a-pull-request-to-an-issue#linking-a-pull-request-to-an-issue-using-a-keyword) +that will automatically close issues referenced with a keyword (such as "Fixes") by a PR or commit once the PR/commit is merged. +Don't use these keywords. We don't want issues to be automatically closed. We want our testers to independently verify and close them. + +Generally, pull requests should consist of a single logical commit. +However, if your PR is for a large feature, you may need a more logical breakdown of commits. +This is fine as long as each commit is a single logical unit. + +### Writing good commit messages +Git commit messages should explain the how and why of your change and be separated into a brief subject line +followed by a more detailed body. When in doubt, follow this guide for good commit messages and +you can’t go wrong: https://chris.beams.io/posts/git-commit/. + +One particularly useful point made in the above guide is regarding commit subject lines: + +> A properly formed Git commit subject line should always be able to complete the following sentence: +> +> - If applied, this commit will your subject line here + +A simple but effective convention to follow for commits is the “problem / solution” pattern. It looks like this: +``` + + +Problem: + +Solution: +``` + +As an example, here is a commit taken from the rancher/rancher repo: +``` +commit b71ce2892eecb7c87a5212e3486f1de899a694aa +Author: Dan Ramich +Date: Tue Jun 19 11:56:52 2018 -0700 + + Add Validator for RoleTemplate + + Problem: + Builtin RoleTemplates can be updated through the API + + Solution: + Add a Validator to ensure the only field that can be changed on a + builtin RoleTemplate is 'locked' +``` + +### Reviewing, addressing feedback, and merging +Generally, pull requests need two approvals from maintainers to be merged. + +When addressing review feedback, it is helpful to the reviewer if additional changes are made in new commits. +This allows the reviewer to easily see the delta between what they previously reviewed and the changes you added +to address their feedback. + +Once a PR has the necessary approvals, it can be merged. +Here’s how the merge should be handled: +- All PR's should use the “Squash and merge” option. +- Commits and their messages should be consistent - each commit in the PR should form a logical unit with working code. +- The first change requested by a Jitsuin reviewer will be to reorganise the commits into a clean logical structure. +- The smaller a PR the more likely and more easily that the change will be approved. +- Any changes requested by a reviewer should be committed as a 'fixup' commit against the original commit in the PR. +- Once approval is granted any 'fixup' commits should be merged into their respective commits using 'git rebase -i --autosquash'. + +## Developer Certificate Of Origin ## + +To contribute to this project, you must agree to the Developer Certificate of Origin (DCO) for each commit you make. +The DCO is a simple statement that you, as a contributor, have the legal right to make the contribution. + +See the [DCO](DCO) file for the full text of what you must agree to. + +To signify that you agree to the DCO for a commit, you add a line to the git +commit message: + +```txt +Signed-off-by: Jane Smith +``` + +In most cases, you can add this signoff to your commit automatically with the +`-s` flag to `git commit`. Please use your real name and a reachable email address. diff --git a/DCO b/DCO new file mode 100644 index 00000000..912d22ee --- /dev/null +++ b/DCO @@ -0,0 +1,38 @@ +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 3b28a550..f8cd7509 100644 --- a/README.md +++ b/README.md @@ -5,61 +5,68 @@ The standard Jitsuin Archivist python client. Please note that the canonical API for Jitsuin Archivist is always the REST API documented at https://jitsuin-archivist.readthedocs.io -# Development - -## Pre-requisites - -Required tools for this repo are task-runner and docker-ce. - -Install task runner: https://github.com/go-task/task -Install docker-ce: https://docs.docker.com/get-docker/ - -## Workflow - -To see what options are available simply execute: - -```bash -task -``` - -All development is done using a docker image. To create the image execute -the following command. This command only has to be repeated if requirements.txt -or requirements-dev.txt change. - -Dependencies are defined in requirements.txt for the archivist package and -requirements-dev.txt for the tools used to build, test and publish the -archivist package. - -To build the docker builder image: -```bash -task builder -``` - -Make a change to the code and validate the changes: - -```bash -task check -``` +# Installation -If ok run the unittests: +Use standard python pip utility: ```bash -task unittests +python3 -m pip install jitsuin-archivist ``` -If 100% coverage and no test failures generate the wheel: +One can then use the examples code to create assets: + +```python +from archivist.archivist import Archivist +from archivist.errors import ArchivistError + +# Oauth2 token that grants access +with open(".auth_token", mode='r') as tokenfile: + authtoken = tokenfile.read().strip() + +# Initialize connection to Archivist - the URL for production will be different to this URL +arch = Archivist( + "https://soak-0-avid.engineering-k8s-stage-2.dev.wild.jitsuin.io", + auth=authtoken, +) + +# Create a new asset +attrs = { + "arc_display_name": "display_name", # Asset's display name in the user interface + "arc_description": "display_description", # Asset's description in the user interface + "arc_display_type": "desplay_type", # Arc_display_type is a free text field + # allowing the creator of + # an asset to specify the asset + # type or class. Be careful when setting this: + # assets are grouped by type and + # sharing policies can be + # configured to share assets based on + # their arc_display_type. + # So a mistake here can result in asset data being + # under- or over-shared. + "some_custom_attribute": "value" # You can add any custom value as long as + # it does not start with arc_ +} +behaviours = ["Attachments", "Firmware", "LocationUpdate", "Maintenance", "RecordEvidence"] + +# The first argument is the behaviours of the asset +# The second argument is the attributes of the asset +# The third argument is wait for confirmation: +# If @confirm@ is True then this function will not +# return until the asset is confirmed on the blockchain and ready +# to accept events (or an error occurs) +# After an asset is submitted to the blockchain (submitted), +# it will be in the "Pending" status. +# Once it is added to the blockchain, the status will be changed to "Confirmed" +try: + asset = arch.assets.create(behaviours, attrs=attrs, confirm=True) +except Archivisterror as ex: + print("error", ex) +else: + print("asset", asset) -```bash -task wheel -``` - -Lastly to publish the package to PyPi: - -```bash -task publish ``` -Note that this requires credentials and will only normally be done by a Jitsuin -representative. +# Development +See BUILDING.md