Contributions are welcome, and they are greatly appreciated! Every little bit helps, and credit will always be given.
When reporting a bug please include:
- Your operating system name and version.
- Any details about your local setup that might be helpful in troubleshooting.
- Detailed steps to reproduce the bug.
Watchmaker could always use more documentation, whether as part of the official Watchmaker docs, in docstrings, or even on the web in blog posts, articles, and such. The official documentation is maintained within this project in docstrings or in the docs directory. Contributions are welcome, and are made the same way as any other code. See Development guide.
The best way to send feedback is to file an issue on GitHub.
If you are proposing a feature:
- Explain in detail how it would work.
- Keep the scope as narrow as possible, to make it easier to implement.
- Remember that this is a community-driven, open-source project, and that code contributions are welcome. :)
To set up watchmaker
for local development:
-
Fork watchmaker (look for the "Fork" button).
-
Clone your fork locally and update the submodules:
git clone https://github.com/your_name_here/watchmaker.git && cd watchmaker git submodule update --init --recursive
-
Create a branch for local development:
git checkout -b name-of-your-bugfix-or-feature
-
Now you can make your changes locally.
-
When you're done making changes, use tox to run the linter, the tests, and the doc builder:
tox
NOTE: This will test the package in all versions of Python listed in
tox.ini
. Iftox
cannot find the interpreter for the version, the test will fail with anInterpreterNotFound
error. This is ok, as long as at least one interpreter runs and the tests pass. You can also specify which tox environments to execute, which can be used to restrict the Python version required.You can also rely on Travis and Appveyor to run the tests after opening the pull request. They will be slower though...
-
In addition to building the package and running the tests,
tox
will build any docs associated with the change. They will be located in thedist/docs
directory. Navigate to the folder, open index.html in your browser, and verify that the doc text and formatting are as you intended.If you only want to build the docs, run:
tox -e docs
Note: depending on your development environment, your browser may not be able to locate to above-created, rendered content. If so, it will be necessary to copy or relocate the documentation to location that your preferred-browser can access them.
-
Commit your changes and push your branch to GitHub:
git add . git commit -m "Your detailed description of your changes." git push origin name-of-your-bugfix-or-feature
-
Submit a pull request through the GitHub website.
If you need some code review or feedback while you are developing the code just open the pull request.
For pull request acceptance, you should:
- Include passing tests (Ensure
tox
is successful). - Update documentation whenever making changes to the API or functionality.
- Add a note to
CHANGELOG.md
about the changes. Include a link to the pull request.
-
The primary tox environments for
watchmaker
include:check
docs
py26
py27
py35
py36
-
To run a subset of environments:
tox -e <env1>,<env2>,<env3>,etc
-
To run a subset of tests:
tox -e <environment> -- py.test -k <test_myfeature>
-
To run all the test environments in parallel, use
detox
:pip install detox detox
To install and run a development branch of watchmaker on a new EC2 instance, specify something like this for EC2 userdata:
-
For Linux: Modify
GIT_REPO
andGIT_BRANCH
to reflect working values for your development build. ModifyPIP_URL
andPYPI_URL
as needed.#!/bin/sh GIT_REPO=https://github.com/<your-github-username>/watchmaker.git GIT_BRANCH=<your-branch> PYPI_URL=https://pypi.org/simple # Setup terminal support for UTF-8 export LC_ALL=en_US.UTF-8 export LANG=en_US.UTF-8 # Install pip python3 -m ensurepip # Install git yum -y install git # Upgrade pip and setuptools python3 -m pip install --index-url="$PYPI_URL" --upgrade pip setuptools # Clone watchmaker git clone "$GIT_REPO" --branch "$GIT_BRANCH" --recursive # Install watchmaker cd watchmaker python3 -m pip install --index-url "$PYPI_URL" --editable . # Run watchmaker watchmaker --log-level debug --log-dir=/var/log/watchmaker
-
For Windows: Modify
GitRepo
andGitBranch
to reflect working values for your development build. Optionally modifyBootstrapUrl
,PythonUrl
,GitUrl
, andPypiUrl
as needed.<powershell> $GitRepo = "https://github.com/<your-github-username>/watchmaker.git" $GitBranch = "<your-branch>" $BootstrapUrl = "https://watchmaker.cloudarmor.io/releases/latest/watchmaker-bootstrap.ps1" $PythonUrl = "https://www.python.org/ftp/python/3.10.11/python-3.10.11-amd64.exe" $GitUrl = "https://github.com/git-for-windows/git/releases/download/v2.40.1.windows.1/Git-2.40.1-64-bit.exe" $PypiUrl = "https://pypi.org/simple" # Use TLS 1.2+ [Net.ServicePointManager]::SecurityProtocol = "Tls12, Tls13" # Download bootstrap file $BootstrapFile = "${Env:Temp}\$(${BootstrapUrl}.split("/")[-1])" (New-Object System.Net.WebClient).DownloadFile($BootstrapUrl, $BootstrapFile) # Install python and git & "$BootstrapFile" ` -PythonUrl "$PythonUrl" ` -GitUrl "$GitUrl" ` -Verbose -ErrorAction Stop # Upgrade pip and setuptools python -m pip install --index-url="$PypiUrl" --upgrade pip setuptools # Clone watchmaker git clone "$GitRepo" --branch "$GitBranch" --recursive # Install watchmaker cd watchmaker python -m pip install --index-url "$PypiUrl" --editable . # Run watchmaker watchmaker --log-level debug --log-dir=C:\Watchmaker\Logs </powershell>