Initial drafts
parent
29db2326ca
commit
86a12fcaa4
|
@ -0,0 +1,10 @@
|
||||||
|
=========
|
||||||
|
Changelog
|
||||||
|
=========
|
||||||
|
|
||||||
|
Version 1
|
||||||
|
===========
|
||||||
|
|
||||||
|
- First created
|
||||||
|
- Built in Python instead of bash
|
||||||
|
|
|
@ -0,0 +1,261 @@
|
||||||
|
============
|
||||||
|
Contributing
|
||||||
|
============
|
||||||
|
|
||||||
|
Welcome to ``hetrixtools-freebsd`` contributor's guide.
|
||||||
|
|
||||||
|
This document focuses on getting any potential contributor familiarized
|
||||||
|
with the development processes, but `other kinds of contributions`_ are also
|
||||||
|
appreciated.
|
||||||
|
|
||||||
|
If you are new to using git_ or have never collaborated in a project previously,
|
||||||
|
please have a look at `contribution-guide.org`_. Other resources are also
|
||||||
|
listed in the excellent `guide created by FreeCodeCamp`_ [#contrib1]_.
|
||||||
|
|
||||||
|
Please notice, all users and contributors are expected to be **open,
|
||||||
|
considerate, reasonable, and respectful**. When in doubt, `Python Software
|
||||||
|
Foundation's Code of Conduct`_ is a good reference in terms of behavior
|
||||||
|
guidelines.
|
||||||
|
|
||||||
|
|
||||||
|
Issue Reports
|
||||||
|
=============
|
||||||
|
|
||||||
|
If you experience bugs or general issues with ``hetrixtools-freebsd``, please have a look
|
||||||
|
on the `issue tracker`_. If you don't see anything useful there, please feel
|
||||||
|
free to fire an issue report.
|
||||||
|
|
||||||
|
.. tip::
|
||||||
|
Please don't forget to include the closed issues in your search.
|
||||||
|
Sometimes a solution was already reported, and the problem is considered
|
||||||
|
**solved**.
|
||||||
|
|
||||||
|
New issue reports should include information about your programming environment
|
||||||
|
(e.g., operating system, Python version) and steps to reproduce the problem.
|
||||||
|
Please try also to simplify the reproduction steps to a very minimal example
|
||||||
|
that still illustrates the problem you are facing. By removing other factors,
|
||||||
|
you help us to identify the root cause of the issue.
|
||||||
|
|
||||||
|
|
||||||
|
Documentation Improvements
|
||||||
|
==========================
|
||||||
|
|
||||||
|
You can help improve ``hetrixtools-freebsd`` docs by making them more readable and coherent, or
|
||||||
|
by adding missing information and correcting mistakes.
|
||||||
|
|
||||||
|
``hetrixtools-freebsd`` documentation uses Sphinx_ as its main documentation compiler.
|
||||||
|
This means that the docs are kept in the same repository as the project code, and
|
||||||
|
that any documentation update is done in the same way was a code contribution.
|
||||||
|
|
||||||
|
When working on documentation changes in your local machine, you can
|
||||||
|
compile them using |tox|_::
|
||||||
|
|
||||||
|
tox -e docs
|
||||||
|
|
||||||
|
and use Python's built-in web server for a preview in your web browser
|
||||||
|
(``http://localhost:8000``)::
|
||||||
|
|
||||||
|
python3 -m http.server --directory 'docs/_build/html'
|
||||||
|
|
||||||
|
|
||||||
|
Code Contributions
|
||||||
|
==================
|
||||||
|
|
||||||
|
Submit an issue
|
||||||
|
---------------
|
||||||
|
|
||||||
|
Before you work on any non-trivial code contribution it's best to first create
|
||||||
|
a report in the `issue tracker`_ to start a discussion on the subject.
|
||||||
|
This often provides additional considerations and avoids unnecessary work.
|
||||||
|
|
||||||
|
Create an environment
|
||||||
|
---------------------
|
||||||
|
|
||||||
|
Before you start coding, we recommend creating an isolated `virtual
|
||||||
|
environment`_ to avoid any problems with your installed Python packages.
|
||||||
|
This can easily be done via either |virtualenv|_::
|
||||||
|
|
||||||
|
virtualenv <PATH TO VENV>
|
||||||
|
source <PATH TO VENV>/bin/activate
|
||||||
|
|
||||||
|
Clone the repository
|
||||||
|
--------------------
|
||||||
|
|
||||||
|
#. Create an user account on |the repository service| if you do not already have one.
|
||||||
|
#. Fork the project repository_: click on the *Fork* button near the top of the
|
||||||
|
page. This creates a copy of the code under your account on |the repository service|.
|
||||||
|
#. Clone this copy to your local disk::
|
||||||
|
|
||||||
|
git clone git@github.com:YourLogin/hetrixtools-freebsd.git
|
||||||
|
cd hetrixtools-freebsd
|
||||||
|
|
||||||
|
#. You should run::
|
||||||
|
|
||||||
|
pip install -U pip setuptools -e .
|
||||||
|
|
||||||
|
to be able to import the package under development in the Python REPL.
|
||||||
|
|
||||||
|
.. todo:: if you are not using pre-commit, please remove the following item:
|
||||||
|
|
||||||
|
#. Install |pre-commit|_::
|
||||||
|
|
||||||
|
pip install pre-commit
|
||||||
|
pre-commit install
|
||||||
|
|
||||||
|
``hetrixtools-freebsd`` comes with a lot of hooks configured to automatically help the
|
||||||
|
developer to check the code being written.
|
||||||
|
|
||||||
|
Implement your changes
|
||||||
|
----------------------
|
||||||
|
|
||||||
|
#. Create a branch to hold your changes::
|
||||||
|
|
||||||
|
git checkout -b my-feature
|
||||||
|
|
||||||
|
and start making changes. Never work on the main branch!
|
||||||
|
|
||||||
|
#. Start your work on this branch. Don't forget to add docstrings_ to new
|
||||||
|
functions, modules and classes, especially if they are part of public APIs.
|
||||||
|
|
||||||
|
#. Add yourself to the list of contributors in ``AUTHORS.rst``.
|
||||||
|
|
||||||
|
#. When you’re done editing, do::
|
||||||
|
|
||||||
|
git add <MODIFIED FILES>
|
||||||
|
git commit
|
||||||
|
|
||||||
|
to record your changes in git_.
|
||||||
|
|
||||||
|
.. important:: Don't forget to add unit tests and documentation in case your
|
||||||
|
contribution adds an additional feature and is not just a bugfix.
|
||||||
|
|
||||||
|
Moreover, writing a `descriptive commit message`_ is highly recommended.
|
||||||
|
In case of doubt, you can check the commit history with::
|
||||||
|
|
||||||
|
git log --graph --decorate --pretty=oneline --abbrev-commit --all
|
||||||
|
|
||||||
|
to look for recurring communication patterns.
|
||||||
|
|
||||||
|
#. Please check that your changes don't break any unit tests with::
|
||||||
|
|
||||||
|
tox
|
||||||
|
|
||||||
|
(after having installed |tox|_ with ``pip install tox`` or ``pipx``).
|
||||||
|
|
||||||
|
You can also use |tox|_ to run several other pre-configured tasks in the
|
||||||
|
repository. Try ``tox -av`` to see a list of the available checks.
|
||||||
|
|
||||||
|
Submit your contribution
|
||||||
|
------------------------
|
||||||
|
|
||||||
|
#. If everything works fine, push your local branch to |the repository service| with::
|
||||||
|
|
||||||
|
git push -u origin my-feature
|
||||||
|
|
||||||
|
#. Go to the web page of your fork and click |contribute button|
|
||||||
|
to send your changes for review.
|
||||||
|
|
||||||
|
.. todo:: if you are using GitHub, you can uncomment the following paragraph
|
||||||
|
|
||||||
|
Find more detailed information in `creating a PR`_. You might also want to open
|
||||||
|
the PR as a draft first and mark it as ready for review after the feedbacks
|
||||||
|
from the continuous integration (CI) system or any required fixes.
|
||||||
|
|
||||||
|
|
||||||
|
Troubleshooting
|
||||||
|
---------------
|
||||||
|
|
||||||
|
The following tips can be used when facing problems to build or test the
|
||||||
|
package:
|
||||||
|
|
||||||
|
#. Make sure to fetch all the tags from the upstream repository_.
|
||||||
|
The command ``git describe --abbrev=0 --tags`` should return the version you
|
||||||
|
are expecting. If you are trying to run CI scripts in a fork repository,
|
||||||
|
make sure to push all the tags.
|
||||||
|
You can also try to remove all the egg files or the complete egg folder, i.e.,
|
||||||
|
``.eggs``, as well as the ``*.egg-info`` folders in the ``src`` folder or
|
||||||
|
potentially in the root of your project.
|
||||||
|
|
||||||
|
#. Sometimes |tox|_ misses out when new dependencies are added, especially to
|
||||||
|
``setup.cfg`` and ``docs/requirements.txt``. If you find any problems with
|
||||||
|
missing dependencies when running a command with |tox|_, try to recreate the
|
||||||
|
``tox`` environment using the ``-r`` flag. For example, instead of::
|
||||||
|
|
||||||
|
tox -e docs
|
||||||
|
|
||||||
|
Try running::
|
||||||
|
|
||||||
|
tox -r -e docs
|
||||||
|
|
||||||
|
#. Make sure to have a reliable |tox|_ installation that uses the correct
|
||||||
|
Python version (e.g., 3.7+). When in doubt you can run::
|
||||||
|
|
||||||
|
tox --version
|
||||||
|
# OR
|
||||||
|
which tox
|
||||||
|
|
||||||
|
If you have trouble and are seeing weird errors upon running |tox|_, you can
|
||||||
|
also try to create a dedicated `virtual environment`_ with a |tox|_ binary
|
||||||
|
freshly installed. For example::
|
||||||
|
|
||||||
|
virtualenv .venv
|
||||||
|
source .venv/bin/activate
|
||||||
|
.venv/bin/pip install tox
|
||||||
|
.venv/bin/tox -e all
|
||||||
|
|
||||||
|
#. `Pytest can drop you`_ in an interactive session in the case an error occurs.
|
||||||
|
In order to do that you need to pass a ``--pdb`` option (for example by
|
||||||
|
running ``tox -- -k <NAME OF THE FALLING TEST> --pdb``).
|
||||||
|
You can also setup breakpoints manually instead of using the ``--pdb`` option.
|
||||||
|
|
||||||
|
|
||||||
|
|
||||||
|
.. [#contrib1] Even though, these resources focus on open source projects and
|
||||||
|
communities, the general ideas behind collaborating with other developers
|
||||||
|
to collectively create software are general and can be applied to all sorts
|
||||||
|
of environments, including private companies and proprietary code bases.
|
||||||
|
|
||||||
|
|
||||||
|
.. <-- start -->
|
||||||
|
.. todo:: Please review and change the following definitions:
|
||||||
|
|
||||||
|
.. |the repository service| replace:: git.paco.to
|
||||||
|
.. |contribute button| replace:: "Create pull request"
|
||||||
|
|
||||||
|
.. _repository: https://git.paco.to/pacohope/hetrixtools-freebsd
|
||||||
|
.. _issue tracker: https://git.paco.to/pacohope/hetrixtools-freebsd/issues
|
||||||
|
.. <-- end -->
|
||||||
|
|
||||||
|
|
||||||
|
.. |virtualenv| replace:: ``virtualenv``
|
||||||
|
.. |pre-commit| replace:: ``pre-commit``
|
||||||
|
.. |tox| replace:: ``tox``
|
||||||
|
|
||||||
|
|
||||||
|
.. _black: https://pypi.org/project/black/
|
||||||
|
.. _CommonMark: https://commonmark.org/
|
||||||
|
.. _contribution-guide.org: https://www.contribution-guide.org/
|
||||||
|
.. _creating a PR: https://docs.github.com/en/pull-requests/collaborating-with-pull-requests/proposing-changes-to-your-work-with-pull-requests/creating-a-pull-request
|
||||||
|
.. _descriptive commit message: https://chris.beams.io/posts/git-commit
|
||||||
|
.. _docstrings: https://www.sphinx-doc.org/en/master/usage/extensions/napoleon.html
|
||||||
|
.. _first-contributions tutorial: https://github.com/firstcontributions/first-contributions
|
||||||
|
.. _flake8: https://flake8.pycqa.org/en/stable/
|
||||||
|
.. _git: https://git-scm.com
|
||||||
|
.. _GitHub's fork and pull request workflow: https://guides.github.com/activities/forking/
|
||||||
|
.. _guide created by FreeCodeCamp: https://github.com/FreeCodeCamp/how-to-contribute-to-open-source
|
||||||
|
.. _Miniconda: https://docs.conda.io/en/latest/miniconda.html
|
||||||
|
.. _MyST: https://myst-parser.readthedocs.io/en/latest/syntax/syntax.html
|
||||||
|
.. _other kinds of contributions: https://opensource.guide/how-to-contribute
|
||||||
|
.. _pre-commit: https://pre-commit.com/
|
||||||
|
.. _PyPI: https://pypi.org/
|
||||||
|
.. _PyScaffold's contributor's guide: https://pyscaffold.org/en/stable/contributing.html
|
||||||
|
.. _Pytest can drop you: https://docs.pytest.org/en/stable/how-to/failures.html#using-python-library-pdb-with-pytest
|
||||||
|
.. _Python Software Foundation's Code of Conduct: https://www.python.org/psf/conduct/
|
||||||
|
.. _reStructuredText: https://www.sphinx-doc.org/en/master/usage/restructuredtext/
|
||||||
|
.. _Sphinx: https://www.sphinx-doc.org/en/master/
|
||||||
|
.. _tox: https://tox.wiki/en/stable/
|
||||||
|
.. _virtual environment: https://realpython.com/python-virtual-environments-a-primer/
|
||||||
|
.. _virtualenv: https://virtualenv.pypa.io/en/stable/
|
||||||
|
|
||||||
|
.. _GitHub web interface: https://docs.github.com/en/repositories/working-with-files/managing-files/editing-files
|
||||||
|
.. _GitHub's code editor: https://docs.github.com/en/repositories/working-with-files/managing-files/editing-files
|
|
@ -0,0 +1,123 @@
|
||||||
|
# This file is used to configure your project.
|
||||||
|
# Read more about the various options under:
|
||||||
|
# https://setuptools.pypa.io/en/latest/userguide/declarative_config.html
|
||||||
|
# https://setuptools.pypa.io/en/latest/references/keywords.html
|
||||||
|
|
||||||
|
[metadata]
|
||||||
|
name = hetrixtools-freebsd
|
||||||
|
description = A python script that sends system info to HetrixTools monitoring
|
||||||
|
author = Paco Hope
|
||||||
|
author_email = github@filter.paco.to
|
||||||
|
license = MIT
|
||||||
|
license_files = LICENSE.txt
|
||||||
|
long_description = file: README.rst
|
||||||
|
long_description_content_type = text/x-rst; charset=UTF-8
|
||||||
|
url = https://github.com/pyscaffold/pyscaffold/
|
||||||
|
# Add here related links, for example:
|
||||||
|
project_urls =
|
||||||
|
Documentation = https://pyscaffold.org/
|
||||||
|
Source = https://git.paco.to/pacohope/hetrixtools-freebsd
|
||||||
|
Changelog = https://git.paco.to/pacohope/hetrixtools-freebsd/src/CHANGELOG.rst
|
||||||
|
Tracker = https://git.paco.to/pacohope/hetrixtools-freebsd/issues
|
||||||
|
# Conda-Forge = https://anaconda.org/conda-forge/pyscaffold
|
||||||
|
# Download = https://pypi.org/project/PyScaffold/#files
|
||||||
|
Twitter = https://infosec.exchange/@paco
|
||||||
|
|
||||||
|
# Change if running only on Windows, Mac or Linux (comma-separated)
|
||||||
|
platforms = FreeBSD
|
||||||
|
|
||||||
|
# Add here all kinds of additional classifiers as defined under
|
||||||
|
# https://pypi.org/classifiers/
|
||||||
|
classifiers =
|
||||||
|
Development Status :: 4 - Beta
|
||||||
|
Programming Language :: Python
|
||||||
|
|
||||||
|
|
||||||
|
[options]
|
||||||
|
zip_safe = False
|
||||||
|
packages = find_namespace:
|
||||||
|
include_package_data = True
|
||||||
|
package_dir =
|
||||||
|
=src
|
||||||
|
|
||||||
|
# Require a min/specific Python version (comma-separated conditions)
|
||||||
|
python_requires = >=3.9
|
||||||
|
|
||||||
|
# Add here dependencies of your project (line-separated), e.g. requests>=2.2,<3.0.
|
||||||
|
# Version specifiers like >=2.2,<3.0 avoid problems due to API changes in
|
||||||
|
# new major versions. This works if the required packages follow Semantic Versioning.
|
||||||
|
# For more information, check out https://semver.org/.
|
||||||
|
install_requires =
|
||||||
|
importlib-metadata; python_version<"3.9"
|
||||||
|
|
||||||
|
|
||||||
|
[options.packages.find]
|
||||||
|
where = src
|
||||||
|
exclude =
|
||||||
|
tests
|
||||||
|
|
||||||
|
[options.extras_require]
|
||||||
|
# Add here additional requirements for extra features, to install with:
|
||||||
|
# `pip install hetrixtools-freebsd[PDF]` like:
|
||||||
|
# PDF = ReportLab; RXP
|
||||||
|
|
||||||
|
# Add here test requirements (semicolon/line-separated)
|
||||||
|
testing =
|
||||||
|
setuptools
|
||||||
|
pytest
|
||||||
|
pytest-cov
|
||||||
|
|
||||||
|
[options.entry_points]
|
||||||
|
# Add here console scripts like:
|
||||||
|
# console_scripts =
|
||||||
|
# script_name = hetrixtools_freebsd.module:function
|
||||||
|
# For example:
|
||||||
|
# console_scripts =
|
||||||
|
# fibonacci = hetrixtools_freebsd.skeleton:run
|
||||||
|
# And any other entry points, for example:
|
||||||
|
# pyscaffold.cli =
|
||||||
|
# awesome = pyscaffoldext.awesome.extension:AwesomeExtension
|
||||||
|
|
||||||
|
[tool:pytest]
|
||||||
|
# Specify command line options as you would do when invoking pytest directly.
|
||||||
|
# e.g. --cov-report html (or xml) for html/xml output or --junitxml junit.xml
|
||||||
|
# in order to write a coverage file that can be read by Jenkins.
|
||||||
|
# CAUTION: --cov flags may prohibit setting breakpoints while debugging.
|
||||||
|
# Comment those flags to avoid this pytest issue.
|
||||||
|
addopts =
|
||||||
|
--cov hetrixtools_freebsd --cov-report term-missing
|
||||||
|
--verbose
|
||||||
|
norecursedirs =
|
||||||
|
dist
|
||||||
|
build
|
||||||
|
.tox
|
||||||
|
testpaths = tests
|
||||||
|
# Use pytest markers to select/deselect specific tests
|
||||||
|
# markers =
|
||||||
|
# slow: mark tests as slow (deselect with '-m "not slow"')
|
||||||
|
# system: mark end-to-end system tests
|
||||||
|
|
||||||
|
[devpi:upload]
|
||||||
|
# Options for the devpi: PyPI server and packaging tool
|
||||||
|
# VCS export must be deactivated since we are using setuptools-scm
|
||||||
|
no_vcs = 1
|
||||||
|
formats = bdist_wheel
|
||||||
|
|
||||||
|
[flake8]
|
||||||
|
# Some sane defaults for the code style checker flake8
|
||||||
|
max_line_length = 88
|
||||||
|
extend_ignore = E203, W503
|
||||||
|
# ^ Black-compatible
|
||||||
|
# E203 and W503 have edge cases handled by black
|
||||||
|
exclude =
|
||||||
|
.tox
|
||||||
|
build
|
||||||
|
dist
|
||||||
|
.eggs
|
||||||
|
docs/conf.py
|
||||||
|
|
||||||
|
[pyscaffold]
|
||||||
|
# PyScaffold's parameters when the project was created.
|
||||||
|
# This will be used when updating. Do not change!
|
||||||
|
version = 4.5
|
||||||
|
package = hetrixtools_freebsd
|
Loading…
Reference in New Issue