Contributing to getmac

Thanks for taking an interest in this awesome little project. We love to bring new members into the community, and can always use the help.

Resources

Code requirements

Your code must:

  • Have tests

  • Work with all supported Python versions

  • Work on all supported platforms

  • Pass linting (code quality checks)

  • Pass CI (GitHub Actions)

  • Adhere to the Code of Conduct

Most of these requirements are checked in CI (GitHub Actions), including Python versions and most supported platforms. Code is formatted with Ruff’s formatter. You can write whatever format you want, as long as you run the formatter before pushing, you’re good (pdm run format).

Please be respectful and follow the Code of Conduct. Memes, references, and jokes are OK. Be nice, we’re all human, and code is the great equalizer.

Checklist before submitting a pull request

  • [ ] Code is formatted using ruff (pdm run format)

  • [ ] All tests run and pass locally

    • [ ] Tests: pdm run test

    • [ ] Benchmarks: pdm run benchmark

    • [ ] Lint: pdm run lint

  • [ ] Update the CHANGELOG (if applicable, for non-trivial changes)

  • [ ] Add your name to the contributors list in the README (please include what your contribution was after your name)

Checklist before a Pull Request will be merged

  • [ ] All tests pass in GitHub Actions

  • [ ] Code has been reviewed by at least one maintainer

  • [ ] Coverage has NOT decreased

Where to contribute

Good for beginners

  • Sample collection (see section below)

  • Platform testing (see section below)

  • Bug reports!

  • Documentation (including fixes for grammar and spelling)

  • Improving and adding tests for existing samples

Main areas of focus

  • Writing parsers for new commands (Example: netsh int ipv6)

  • Addressing missing functionality (Example: default interface detection for IPv6 on Windows)

  • Adding new features (Example: ability to find MAC by interface index integer)

  • Adding tests for internal methods and mocking where necessary

Platform testing

Help is dearly needed on testing and rooting out differences in various platforms and configurations. At a basic level, this involves just running the tests on any platforms you use. Open issues for any bugs or quirks you discover, or if you’re feeling adventurous, fix it yourself!

Any platform is fair game! The following are platforms of special interest:

  • MacOS/OSX (This requires owning a Mac, and is the area most sorely in need of testing)

  • Legacy Windows (7, 8, 8.1)

  • Windows Server (all versions)

  • Arch Linux

  • BSDs

Sample collection

Examples of output of various commands is an easy way contribute that is still incredibly helpful.

  1. Run the command

  2. Copy/paste the output (or redirect output of command, tee is helpful here) into an appropriately named .out file in samples/

  3. That’s it!

Getting started

  1. Create your own fork of the code through GitHub web interface (Here’s a Guide)

  2. Clone the fork to your computer. This can be done using the GitHub desktop GUI , git clone <fork-url>, or the Git tools in your favorite editor or IDE.

  3. Create and checkout a new branch in the fork with either your username (e.g. “ghostofgoes”), or the name of the feature or issue you’re working on (e.g. “openbsd-support”). Again, this can be done using the GUI, your favorite editor, or git checkout -b <branch> origin/<branch>.

  4. Install PDM: https://pdm-project.org/en/latest/#installation

  5. Create local environment:

    pdm install -d

  6. Ensure tests and linting works:

    pdm run lint
pdm run test

  7. Write some code! Git commit messages should information about what changed, and if it’s relevant, the rationale (thinking) for the change.

  8. Format your code:

     pdm run format

  9. Follow the checklist in the pull request template

  10. Submit a pull request!

Bug reports

Filing a bug report:

  1. Answer these questions:

    • [ ] What version of getmac are you using? (getmac --version)

    • [ ] What operating system and processor architecture are you using?

    • [ ] What version of Python are you using?

    • [ ] What did you do?

    • [ ] What did you expect to see?

    • [ ] What did you see instead?

  2. Put any excessive output into a GitHub Gist and include a link in the issue.

  3. Tag the issue with “Bug”

NOTE: If the issue is a potential security vulnerability, do NOT open an issue! Instead, email: ghostofgoes(at)gmail(dot)com

Features and ideas

Ideas for features or other things are welcomed. Open an issue on GitHub detailing the idea, and tag it appropriately (e.g. “Feature” for a new feature).

Resources

Regex resources (regular expressions)

Commands

# Create development environment
pdm install -d

# List scripts, these can be run with "pdm run"
pdm run -l

# Run tests
pdm run test

# Lint checks
pdm run lint

# Run getmac CLI
pdm run getmac --help
pdm run getmac --version

Documentation

The docs are built using Sphinx. They are located in the docs/ folder, and the configuration is in docs/conf.py.

To build docs locally:

pdm run docs