Merge pull request #151 from britive/develop

v1.8.0rc1

Author: theborch

CHANGELOG.md

@@ -1,32 +1,37 @@
+# CONTRIBUTING
+
+> __TODO:__ _add development/convention sections._
+
 ## Local Install
 
-~~~
+```sh
 pip install --editable .
-~~~
+```
 
 ## Build
 
-* Update version in `setup.cfg` and `src/pybritive/__init__.py` (TODO: create some pre-build script that will update one of these automatically)
+* Update version in `src/pybritive/__init__.py`
 * Push code to GitHub
 * Cut a new PR and merge when appropriate
 * Run below commands
 
-
-~~~
+```sh
 python -m pip install --upgrade build
 python -m build
-~~~
+```
 
 * Cut a new release in GitHub with the version tag
 * Add the assets from `dist` directory to the release
 
 ## Github Actions
+
 There are 2 Github Actions in play that publish to PyPI.
 
 1. Trigger off of a push to the `develop` branch. Will deploy to test PyPI.
 2. Trigger off of a new release being published. Will deploy to real PyPI.
 
 ## Testing
+
 It is generally advisable to set environment variable `PYBRITIVE_HOME_DIR` to some temp location if you
 will be performing the full suite of tests. This will ensure that no changes are made to your existing
 configuration or credentials.
@@ -35,55 +40,65 @@ Environment variables that should be set for testing include the following.
 
 * `PYBRITIVE_HOME_DIR` - a path to a home directory where `.britive` directory will be created
 * `PYBRITIVE_TEST_TENANT` - the tenant name to be used for testing purposes
-* `PYBRITIVE_NPM_IMPORT_PROFILE_ALIAS_VALUE` - the IDs of a profile that can be used to test the import process. This should be in format `"appid/envid/profileid/appname"`.
+* `PYBRITIVE_NPM_IMPORT_PROFILE_ALIAS_VALUE` - the IDs of a profile that can be used to test the import process. This
+should be in format `"appid/envid/profileid/appname"`
 * `PYBRITIVE_ENCRYPTED_CREDENTIAL_PASSPHRASE` - the password for encrypted file credential storage
-* `PYBRITIVE_PREPARE_DOT_BRITIVE` - set to true if you want to have the `.britive` directory cleared before starting the tests
-* `BRITIVE_API_TOKEN` - set if you want to avoid an interactive login process - the interactive login process will need to be tested separately
+* `PYBRITIVE_PREPARE_DOT_BRITIVE` - set to true if you want to have the `.britive` directory cleared before starting the
+tests
+* `BRITIVE_API_TOKEN` - set if you want to avoid an interactive login process - the interactive login process will need
+to be tested separately
 
-Create `./testing-variables.txt` and load what you need so you can easily re-create the needed variables. This file is in `.gitignore`. 
+Create `./testing-variables.txt` and load what you need so you can easily re-create the needed variables. This file is
+in `.gitignore`.
 
 Package the code locally with `pip install -e .` so pytest can run against the python package.
-Then `pytest tests/ -vvv` to perform the testing. 
+Then `pytest tests/ -vvv` to perform the testing.
+
+The identity used for testing will require access to at least one profile to test `checkout` and `checkin`.
+Additionally, the identity will need access to 2 secrets:
 
-The identity used for testing will require access to at least one profile to test `checkout` and `checkin`. 
-Additionally, the identity will need access to 2 secrets
-* one standard secret with path `/pybritive-test-standard` to test `view` - the value of the secret should be generic note with note of `test`
-* one file secret with path `/pybritive-test-file` to test `download` - the filename should be `pybritive-test-secret-file.txt` and contain contents of `test`
+* one standard secret with path `/pybritive-test-standard` to test `view` - the value of the secret should be generic
+note with note of `test`
+* one file secret with path `/pybritive-test-file` to test `download` - the filename should be
+`pybritive-test-secret-file.txt` and contain contents of `test`
 
 ## Docs
 
-https://docs.readthedocs.io/en/stable/intro/getting-started-with-mkdocs.html
+[mkdocs](https://docs.readthedocs.io/en/stable/intro/getting-started-with-mkdocs.html)
 
 To set up the doc infrastructure the first time run the following from the base directory
 
-~~~
+```sh
 pip install mkdocs
 mkdocs new .
-~~~
+```
 
 For real time local updates in HTML...
-~~~
+
+```sh
 mkdocs serve
-~~~
+```
 
 To build...
 
-~~~
+```sh
 mkdocs build
-~~~
+```
 
 This will create a new directory `site`.
 
 As we are using source code control we have added `site/` to `.gitignore` so you will have to build the docs locally.
 
-We will ultimately deploy via GitHub pages. But you can also copy everything in `site/` and host as a static website anywhere you want.
+We will ultimately deploy via GitHub pages. But you can also copy everything in `site/` and host as a static website
+anywhere you want.
 
 To deploy to GitHub project pages....
 
-~~~
+```sh
 # checkout whichever branch is needed (main or develop most likely)
 mkdocs gh-deploy
-~~~
+```
 
-This will build the docs by performing the actions of `mkdocs build` and shove those built docs into the `gh-pages` branch of the repo.
-`gh-pages` is auto-linked to `https://britive.github.io/python-cli/` and will update that site in near real time.
+This will build the docs by performing the actions of `mkdocs build` and shove those built docs into the `gh-pages`
+branch of the repo. `gh-pages` is auto-linked to `https://britive.github.io/python-cli/` and will update that site in
+near real time.

TECH_README.md CONTRIBUTING.mdTECH_README.md renamed to CONTRIBUTING.md

@@ -4,34 +4,41 @@ PyBritive is intended to be used as a CLI application for communicating with the
 
 ## Installation
 
-`pybritive` will be installed via Python `pip`. 
+`pybritive` will be installed via the Python package installer, `pip`.
 
-~~~bash
+```sh
 pip install pybritive
-~~~
+```
 
-Or you can always pull the latest version directly from GitHub using one of the following commands.
+> _NOTE: The end user is free to install the CLI into a virtual environment or in the global scope,
+> _so it is available everywhere._
 
-~~~
-pip install $(curl -s https://api.github.com/repos/britive/python-cli/releases/latest | jq -r '.assets[] | select(.content_type == "application/x-gzip") | .browser_download_url')
+## Alternate Installation
 
-OR
+You can always pull the latest version directly from GitHub using one of the following commands:
 
-pip install $(curl -s https://api.github.com/repos/britive/python-cli/releases/latest | grep "browser_download_url.*.tar.gz" | cut -d : -f 2,3 | tr -d \")
-~~~
+```sh
+pip install $(curl -s https://api.github.com/repos/britive/python-cli/releases/latest \
+    | jq -r '.assets[] | select(.content_type == "application/x-gzip") | .browser_download_url')
+```
 
-The end user is free to install the CLI into a virtual environment or in the global scope, so it is available
-everywhere.
+Or
 
+```sh
+pip install $(curl -s https://api.github.com/repos/britive/python-cli/releases/latest \
+    | grep "browser_download_url.*.tar.gz" | cut -d : -f 2,3 | tr -d \")
+```
 
 ## Documentation
 
-https://britive.github.io/python-cli/
-
+* [Britive CLI](https://britive.github.io/python-cli)
 
 ## Community Projects
 
-Note: Britive, Inc. does not provide support for community projects. Community projects are also not considered when ensuring backwards compatibility for releases. The list below is provided as-is and use of these projects is subject to the licensing/restrictions of each individual project.
-
-* `vim-britive`: https://github.com/pbnj/vim-britive
+> _NOTE:_
+> _Britive, Inc. does not provide support for community projects._
+> _Community projects are also not considered when ensuring backwards compatibility for releases._
+> _The list below is provided as-is and use of these projects is subject to the licensing/restrictions of each_
+> _individual project._
 
+* [`vim-britive`](https://github.com/pbnj/vim-britive)