fix: enable builds on Windows (#215)

Signed-off-by: Phil Adams <[email protected]>

Author: padamstx

.pylintrc

@@ -61,7 +61,8 @@ disable=too-many-arguments,
         useless-suppression,
         deprecated-pragma,
         use-symbolic-message-instead,
-        invalid-name
+        invalid-name,
+        global-statement
 
 # Enable the message, report, category or checker with the given id(s). You can
 # either give multiple identifier separated by comma (,) or put this option

CONTRIBUTING.md

@@ -12,6 +12,21 @@ Before that, please search for similar issues. It's possible that someone has al
 For general guidance on contributing to this project, please see
 [this link](https://github.com/IBM/ibm-cloud-sdk-common/blob/main/CONTRIBUTING_python.md)
 
+# Prerequisites
+The following tools are required in order to build this project:
+* Git
+* A modern version of the `make` utility.  
+    Note: Windows users will likely need to install one of the various 
+    [make utilities available for Windows](https://www.google.com/search?q=make+utility+for+windows).
+* A version of [Python](https://www.python.org/downloads/) that is >= the minimum version supported by the project.  
+    Note: It is highly recommended that you use Python's `venv` module to create a virtual environment for
+    your project.  This will allow you to work on this project (including the installation of any project dependencies)
+    without affecting your computer's Python installation or any other Python projects on your computer.
+    More details are available [here](update_service.md#initial-project-setup).
+
+Windows users might find it more convenient to use
+[`Windows Subsystem for Linux (WSL)`](https://learn.microsoft.com/en-us/windows/wsl/about)
+or [`Cygwin`](https://www.cygwin.com/) when making contributions to this project.
+
 # Updating an existing service within the SDK
-For instructions on updating an existing service within the SDK, please see
-[this link](update_service.md)
+For instructions on updating an existing service within the SDK, please see [update_service.md](update_service.md)

Makefile

@@ -2,37 +2,42 @@
 # to be ready for development work in the local sandbox.
 # example: "make setup"
 
+PYTHON=python
+LINT_DIRS=ibm_platform_services test examples
+
 setup: deps dev_deps install_project
 
 all: upgrade_pip setup test-unit lint
 
 ci: setup test-unit lint
 
 upgrade_pip:
-	python -m pip install --upgrade pip
+	${PYTHON} -m pip install --upgrade pip
 
 deps:
-	python -m pip install -r requirements.txt
+	${PYTHON} -m pip install -r requirements.txt
 
 dev_deps:
-	python -m pip install -r requirements-dev.txt
+	${PYTHON} -m pip install -r requirements-dev.txt
 
 install_project:
-	python -m pip install -e .
+	${PYTHON} -m pip install -e .
 
 test: test-unit test-int
 
 test-unit:
-	python -m pytest --cov=ibm_platform_services test/unit
+	${PYTHON} -m pytest --cov=ibm_platform_services test/unit
 
 test-int:
-	python -m pytest test/integration
+	${PYTHON} -m pytest test/integration
 
 test-examples:
-	python -m pytest examples
+	${PYTHON} -m pytest examples
 
 lint:
-	./pylint.sh && black --check .
+	${PYTHON} -m pylint ${LINT_DIRS}
+	black --check ${LINT_DIRS}
 
 lint-fix:
-	black .
+	black ${LINT_DIRS}
+	

pylint.sh

@@ -49,7 +49,10 @@ to your external github.com id. The id linking step will also result in an invit
 `github.com/IBM` org. Accept that invitation.
 3. If you do not yet have "push" access to the SDK project, contact the project maintainer to request push access
 (you must be a member of the github.com/IBM org).
-4. Make sure that your installed version of Python is >= the minimum version supported by the SDK project.
+4. Make sure that you have installed the [tools required to build the project](CONTRIBUTING.md#prerequisites).
+5. To update a service, make sure the following additional tools are installed:
+* The [IBM OpenAPI Validator](https://github.com/IBM/openapi-validator)
+* The [IBM OpenAPI SDK Generator](github.ibm.com/CloudEngineering/openapi-sdkgen)
 
 ## Initial project setup
 1. Clone/fork the repo.  If you have push access (see above), you can clone the repo directly (no fork).  
@@ -75,10 +78,13 @@ git pull
 # create a virtual environment using the current python version, store in "./venv"
 python -m venv ./venv
 
-# source in the resulting "activate" script to use the virtual environment
+# Activate the virtual environment
+# On Linux/MacOS source in the "activate" script created by the "venv" module:
 . venv/bin/activate
+# On Windows, run the "activate" script created by the "venv" module:
+venv/scripts/activate
 
-# Install dependencies, run unit-tests and link-check the project
+# Install dependencies, run unit-tests and lint-check the project
 make all
 ```
 4. Make sure that the integration tests and working examples run clean for your service.