Docs: updated readme again, plus contribution guidelines and develope…

…rs' guide.

CONTRIBUTING.md

@@ -12,6 +12,10 @@ By contributing to pyOCD you agree to the [Code of Conduct](CODE_OF_CONDUCT.md).
 Contributed source code must follow [PEP8](https://www.python.org/dev/peps/pep-0008/) style
 conventions.
 
+Significant new code must use type annotations. However, until the bulk of pyOCD code is converted to have type
+annotations, static type checking isn't actual performed by CI. Also, it is perfectly ok to fix bugs without annotating
+the errant module.
+
 Other formatting requirements:
 - 4 space indents, no tabs are allowed.
 - No trailing whitespace.
@@ -30,9 +34,10 @@ Before you submit your changes, please ensure that:
 - Changes have been tested locally to the extent possible. (Obviously, we don't expect you to have as many
   test boards as we do.)
 
-Please create a pull request in GitHub with your contribution. Before creating the pull request,
-please ensure that all tests pass. We also run the tests on a wide range of boards for every pull
-request using our CI setup. Changes must pass all required pull request checks before they can be accepted.
+Please [create a new pull request](https://github.com/pyocd/pyOCD/pull/new/develop) on GitHub with your contribution.
+The new pull request should target the `develop` branch. Before creating the pull request, please ensure that all tests
+pass. We also run the tests on a wide range of boards for every pull request using our CI setup. Changes must pass all
+required pull request checks before they can be accepted.
 
 The [developers' guide](docs/developers_guide.md) describes how to create your development
 environment. The [automated tests guide](docs/automated_tests.md) provides information about the
@@ -41,7 +46,7 @@ available types of tests and describes how to run the tests.
 
 ## License
 
-By creating a pull request on GitHub, you agree to the [Developer Certificate of
+By creating a pull request on GitHub asking to merge your content into pyOCD, you agree to the [Developer Certificate of
 Origin](https://developercertificate.org), stating that you have the right to grant license to your contribution under
 the Apache 2.0 license.
 
@@ -51,6 +56,8 @@ should use your employer's copyright. If a file is newly added by you, it must c
 your copyright. Please note that we do not list changes in each source file by copyright owner, as this becomes a burden
 to maintain.
 
+PyOCD follows the "inbound = outbound" licensing policy. This is [the default](https://docs.github.com/en/github/site-policy/github-terms-of-service#6-contributions-under-repository-license) for the GitHub Terms of Service.
+
 Contributing source code that is already licensed using a license other than Apache 2.0 is possible, but each
 case must be considered individually. If you are the owner of the source code, then you have the right to
 relicense to Apache 2.0. The most important thing is that the license is compatible with Apache 2.0. Examples

README.md

@@ -13,7 +13,7 @@ See the [wiki news page](https://github.com/pyocd/pyOCD/wiki/News) for all recen
 
 pyOCD is an open source Python package for programming and debugging Arm Cortex-M microcontrollers
 using multiple supported types of USB debug probes. It is fully cross-platform, with support for
-Linux, macOS, and Windows.
+Linux, macOS, Windows, and FreeBSD.
 
 A command line tool is provided that covers most use cases, or you can make use of the Python
 API to enable low-level target control. A common use for the Python API is to run and control CI
@@ -57,7 +57,7 @@ Requirements
 ------------
 
 - Python 3.6.0 or later.†
-- macOS, Linux, or Windows 7 or newer
+- macOS, Linux, Windows 7 or newer, or FreeBSD
 - A recent version of [libusb](https://libusb.info/). See [libusb installation](#libusb-installation) for details.
 - Microcontroller with an Arm Cortex-M CPU
 - Supported debug probe
@@ -108,11 +108,11 @@ _Note: depending on your system, you may need to use `python` instead of `python
 The latest pyOCD package is available [on PyPI](https://pypi.python.org/pypi/pyOCD/) as well as
 [on GitHub](https://github.com/pyocd/pyOCD/releases).
 
-To install the latest prerelease version from the HEAD of the master branch, you can do
+To install the latest prerelease version from the HEAD of the `develop` branch, you can do
 the following:
 
 ```
-$ python3 -mpip install --pre -U git+https://github.com/pyocd/pyOCD.git
+$ python3 -mpip install --pre -U git+https://github.com/pyocd/pyOCD.git@develop
 ```
 
 You can also install directly from the source by cloning the git repository and running:
@@ -144,7 +144,7 @@ automatically via pip dependency management.
 How to install libusb depends on your OS:
 
 - macOS: use Homebrew: `brew install libusb`
-- Linux: should already be installed.
+- Linux and BSD: should already be installed.
 - Windows: download libusb from [libusb.info](https://libusb.info/) and place the .dll file in your Python
   installation folder next to python.exe. Make sure to use the same 32- or 64-bit architecture as
   your Python installation. The latest release is [available on GitHub](https://github.com/libusb/libusb/releases);
@@ -157,8 +157,8 @@ probes from user space. Otherwise you will need to run pyOCD as root, using sudo
 highly discouraged. (You should _never_ run pyOCD as root on any OS.)
 
 To help with this, example udev rules files are included with pyOCD in the
-[udev](https://github.com/pyocd/pyOCD/tree/master/udev) folder. The
-[readme](https://github.com/pyocd/pyOCD/tree/master/udev/README.md) in this folder has detailed
+[udev](https://github.com/pyocd/pyOCD/tree/main/udev) folder. The
+[readme](https://github.com/pyocd/pyOCD/tree/main/udev/README.md) in this folder has detailed
 instructions.
 
 ### Target support
@@ -216,23 +216,22 @@ Eclipse adding `http://embsysregview.sourceforge.net/update` as a software updat
 under the "Help -> Install New Software..." menu item.
 
 
-Development setup
------------------
-
-Please see the [Developers' Guide](docs/developers_guide.md) for instructions on how to set up a
-development environment for pyOCD.
-
-
 Contributions
 -------------
 
-We welcome contributions to pyOCD in any area. Please see the [contribution
-guidelines](CONTRIBUTING.md) for detailed requirements for contributions. In order foster a healthy
-and safe community, we expect contributors to follow the [code of conduct](CODE_OF_CONDUCT.md).
+Join the pyOCD community! We welcome contributions in any area. Please see the [contribution
+guidelines](CONTRIBUTING.md) for detailed requirements. In order foster a healthy
+and safe environment, we expect contributors and all members of the community to follow the
+[code of conduct](CODE_OF_CONDUCT.md).
 
 To report bugs, please [create an issue](https://github.com/pyocd/pyOCD/issues/new) in the
 GitHub project.
 
+Please see the [Developers' Guide](docs/developers_guide.md) for instructions on how to set up a
+development environment for pyOCD.
+
+New pull requests should be [created](https://github.com/pyocd/pyOCD/pull/new/develop) against the `develop` branch.
+
 
 License
 -------

docs/developers_guide.md

@@ -1,21 +1,20 @@
 pyOCD Developers' Guide
 =======================
 
-PyOCD developers are recommended to setup a working environment using
-[virtualenv](https://virtualenv.pypa.io/en/latest/). After cloning the
-code, you can setup a virtualenv and install the pyOCD dependencies for
-the current platform by following the detailed steps below.
-
 ## Setup
 
+PyOCD developers are strongly recommended to setup a working environment using either
+[virtualenv](https://virtualenv.pypa.io/en/latest/) or the built-in `venv` module (only use of virtualenv is shown
+below, but the two are equivalent). After cloning the code, you can setup a virtualenv and install the pyOCD
+dependencies for the current platform by following the detailed steps below.
+
 Install the necessary tools listed below. Skip any step where a compatible tool already exists.
 
-* [Install Python](https://www.python.org/downloads/). It is recommended that you install Python 3.8.0 or above.
-    Add to PATH.
-    *  Note that on Windows, the 32-bit Python 2.7 must be installed for the Python-enabled gdb to
+* [Install Python](https://www.python.org/downloads/) version 3.6.0 or above. Add to PATH.
+    *  Note that on Windows, the 32-bit Python 2.7 must be installed for the Python-enabled `arm-none-eabi-gdb-py` to
         work properly and for the `test/gdb_test.py` functional test to pass.
 * [Install Git](https://git-scm.com/downloads). Add to PATH.
-* [Install virtualenv](https://virtualenv.pypa.io/en/latest/) in your global Python installation, eg: `pip install virtualenv`.
+* [Install virtualenv](https://virtualenv.pypa.io/en/latest/) in your global Python installation, eg: `pip install virtualenv`. Not needed if using the built-in `venv` module.
 * [Install GNU Arm Embedded toolchain](https://developer.arm.com/tools-and-software/open-source-software/developer-tools/gnu-toolchain/gnu-rm).
     This provides `arm-none-eabi-gdb` used for testing the gdbserver. Add to PATH.
 
@@ -51,6 +50,9 @@ $ pip install -r dev-requirements.txt
 See the [porting guide](adding_new_targets.md) for how to add new devices. Of course, we welcome
 all improvements and changes. See the [contributor statement](../CONTRIBUTING.md) for some guidelines.
 
+Normally you should work from the `develop` branch. See the [branch policy](#branch-configuration-policy) below for
+more information about branches.
+
 **Step 4.** Test
 
 To run the unit tests, you can execute the following.
@@ -76,7 +78,18 @@ $ python ./automated_test.py
 **Step 5.** Pull request
 
 Once you are satisfied with your changes and all automated tests pass, please create a
-[new pull request](https://github.com/pyocd/pyOCD/pull/new/master) on GitHub to share your work.
+[new pull request](https://github.com/pyocd/pyOCD/pull/new/develop) against the `develop` branch on GitHub to share your work.
+
+Pull requests should be made after a changeset is [rebased onto `develop`](https://www.atlassian.com/git/tutorials/merging-vs-rebasing/workflow-walkthrough).
+
+
+## Branch configuration policy
+
+There are two primary branches:
+
+- `main`: Stable branch reflecting the most recent release.
+- `develop`: Active development branch for the next version. Merged into `main` at release time.
 
-Pull requests should be made once a changeset is [rebased onto master](https://www.atlassian.com/git/tutorials/merging-vs-rebasing/workflow-walkthrough).
+There may be other development branches present to host long term development of major new features and backwards incompatible changes, such as API changes.
 
+Changes should generally be made against the `develop` branch.