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