Contributing

Contributions are welcome, and they are greatly appreciated! Every little bit helps, and credit will always be given.

Bug Reports

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.

Documentation Improvements

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.

Feature Requests and Feedback

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. :)

Development Guide

To set up watchmaker for local development:

1. Fork watchmaker (look for the “Fork” button).

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

3. Create a branch for local development:

   git checkout -b name-of-your-bugfix-or-feature
   

4. Now you can make your changes locally.

5. 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. If tox cannot find the interpreter for the version, the test will fail with an InterpreterNotFound 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…

6. In addition to building the package and running the tests, tox will build any docs associated with the change. They will be located in the dist/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.

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

8. Submit a pull request through the GitHub website.

Pull Request Guidelines

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:

1. Include passing tests (Ensure tox is successful).

2. Update documentation whenever making changes to the API or functionality.

3. Add a note to CHANGELOG.md about the changes. Include a link to the pull request.

Tox Tips

1. The primary tox environments for watchmaker include:

   • check

   • docs

   • py26

   • py27

   • py35

   • py36

2. To run a subset of environments:

   tox -e <env1>,<env2>,<env3>,etc
   

3. To run a subset of tests:

   tox -e <environment> -- py.test -k <test_myfeature>
   

4. To run all the test environments in parallel, use detox:

   pip install detox
   detox
   

Build a Development Branch in EC2

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 and GIT_BRANCH to reflect working values for your development build. Modify PIP_URL and PYPI_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
  
  # 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 and GitBranch to reflect working values for your development build. Optionally modify BootstrapUrl, PythonUrl, GitUrl, and PypiUrl 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>