#3448 Add standard opensource files (#5)

Author: jitsuineccles

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.
+
+

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 <support@jitsuin.com>.
+
+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/
+

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 <ins>your subject line here</ins>
+
+A simple but effective convention to follow for commits is the “problem / solution” pattern. It looks like this:
+```
+<Subject>
+
+Problem: <Statement of problem>
+
+Solution: <Statement of solution>
+```
+
+As an example, here is a commit taken from the rancher/rancher repo:
+```
+commit b71ce2892eecb7c87a5212e3486f1de899a694aa
+Author: Dan Ramich <danold215@gmail.com>
+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 <jane.smith@example.com>
+```
+
+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.

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.
+

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