diff --git a/.github/CODE_OF_CONDUCT.md b/.github/CODE_OF_CONDUCT.md new file mode 100644 index 0000000..c2ae49b --- /dev/null +++ b/.github/CODE_OF_CONDUCT.md @@ -0,0 +1,12 @@ +# Code of conduct + +Always act with kindness! + +Background and skill levels vary widely, but everyone deserves a welcoming +environment to participate in. Please be considerate to all. + +## Enforcement + +Anything rude, including the one being rude, may be removed from this project. + +Unkind behavior can be reported to a project maintainer and will be addressed. diff --git a/.github/CONTRIBUTING.md b/.github/CONTRIBUTING.md new file mode 100644 index 0000000..011352e --- /dev/null +++ b/.github/CONTRIBUTING.md @@ -0,0 +1,75 @@ +# Contributors guide + +Thank you for your interest in contributing! This is pretty exciting! + +All types of contributions are valued and encouraged, so feel free to get +involved however you'd like! Just please abide by the [code of conduct][conduct] +in any interactions. + +**Outline**: + +- [Submitting issues](#submitting-issues) +- [Suggesting enhancements](#suggesting-enhancements) +- [Improving code health](#improving-code-health) +- [Opening pull requests](#opening-pull-requests) + +## Submitting issues + +Any problems with the code can be reported from [the **Issues** tab][issues]. +Security related concerns should be shared on [the **Security** tab][security]. + +When submitting an issue, please provide enough detail to observe the problem. +Any related information is appreciated too! + +Highlighting issues is very useful for stable software, so thank you. + +Fixes for any open issues are always welcomed by opening a pull request. + +## Suggesting enhancements + +Features that modify existing behavior or add new functionality to suit your own +needs are encouraged! + +Discussion around any changes can happen either on a pull request or an issue +beforehand to help align with the general goals of this project. + +Any miscellaneous musings or random ideations are always so appreciated. + +## Improving code health + +Any efforts to make this project better are also welcomed! These can include +changes or additions to documentation, testing, or other things related to code. + +These changes can usually be proposed directly in a pull request. + +The code is so grateful for these changes. + +## Opening pull requests + +Proposing any changes might be intimidating, but we're all on the same team! + +After you have [created a fork][fork] and made your changes, there are a few +additional checks before opening a pull request: + +- Add an entry to the `CHANGELOG.md` – something brief but descriptive +- Write tests that cover common cases for any changes to the code +- Ensure all documentation is updated – both `godoc` and the outward kinds + +Once this looks good to you, [create a pull request][fork_pr] with the following +information: + +- A title that summarizes the goal of the changes +- A summary of the changes and any notes, as needed + +And with that, you can open the pull request and wait for a review! Woo! Go you! + +For more information on the code processes for this project, check out the +[`MAINTAINERS_GUIDE.md`][maintainers]. + + +[conduct]: ./CODE_OF_CONDUCT.md +[issues]: https://github.com/zimeg/emporia-time/issues +[security]: https://github.com/zimeg/emporia-time/security +[fork]: https://docs.github.com/en/get-started/quickstart/fork-a-repo#forking-a-repository +[fork_pr]: https://docs.github.com/en/pull-requests/collaborating-with-pull-requests/proposing-changes-to-your-work-with-pull-requests/creating-a-pull-request-from-a-fork +[maintainers]: ./MAINTAINERS_GUIDE.md diff --git a/.github/MAINTAINERS_GUIDE.md b/.github/MAINTAINERS_GUIDE.md new file mode 100644 index 0000000..5fe4cd1 --- /dev/null +++ b/.github/MAINTAINERS_GUIDE.md @@ -0,0 +1,101 @@ +# Maintainers guide + +Hey there! It's about time... Watt have you been jouling!? + +**Outline**: + +- [Project setup](#project-setup) +- [Testing](#testing) +- [Merging pull requests](#merging-pull-requests) +- [Runner setup](#runner-setup) + +## Project setup + +After setting up the project for normal usage, you're ready for development! + +An [understanding of Go][learn_go] is a likely prerequisite for any programming +and can be an enjoyable language to learn! + +### Project structure + +This project hopes to use different directories to separate various concerns, +currently using the following structure: + +- `/` – primary project files and metadata for the repository +- `.github/` – information for collaboration and continuous integrations +- `internal/` – helpful utilities needed to create the program +- `pkg/` – various concerns that are pieced together to form the program + +### Makefile commands + +For ease of development, some commands are added in a `Makefile`: + +- `make build` – build the program binary +- `make test` – perform the written code tests +- `make clean` – remove all program artifacts + +The name of the binary can be changed with `make build BIN=timer`. + +## Testing + +All tests should aim to cover common cases, both happy and erroneous, to build +confidence in any changes. + +### Unit tests + +Written tests should reside in a file adjacent to the functionality being tested +and suffixed with `_test.go`. + +All tests can be run with `make test` and example test cases can be found +throughout the repo. + +While coverage isn't critical, various permutations of input are often used to +check edge cases. There's some balance. + +### Integration tests + +Assurance that the program works as expected with the Emporia API can be gained +by running the program with any command: + +```sh +$ make build +$ ./etime sleep 4 +``` + +A smart plug and Emporia credentials are needed for this to be successful. + +### On the remote + +When changes are proposed or made to the remote repository, the full test suite +is performed to verify stability in any changes. + +Additionally, some change to the `CHANGELOG.md` is checked for on pull requests. + +## Merging pull requests + +Confidence in the tests should cover edge cases well enough to trust the suite. +A green status signals nothing broke as a result of changes, and an example run +can be seen in the actions output. + +On any change, the following should be verified before merging: + +- Documentation is correct and updated everywhere necessary +- Code changes move the project in a positive direction + +If that all looks good and the change is solid, the **Squash and merge** awaits. + +## Runner setup + +A self-hosted runner is used to verify valid measurements are made when +monitoring energy usage during the remote integration tests. + +To bring the runner online, [add a **New self-hosted runner**][runner] using a +device connected to a smart plug. + +Then set values for `EMPORIA_DEVICE`, `EMPORIA_USERNAME`, and `EMPORIA_PASSWORD` +in your action repository secrets using your Emporia information. Also add these +for Dependabot to configure this workflow. + + +[learn_go]: https://go.dev/learn/ +[runner]: https://docs.github.com/en/actions/hosting-your-own-runners/managing-self-hosted-runners/adding-self-hosted-runners diff --git a/.github/SECURITY.md b/.github/SECURITY.md new file mode 100644 index 0000000..bd34976 --- /dev/null +++ b/.github/SECURITY.md @@ -0,0 +1,16 @@ +# Security policy + +## Supported versions + +Only the latest released version is supported and will receive security updates. + +## Reporting a vulnerability + +Please privately report security related problems or vulnerabilities using the +**Report a vulnerability** button on [the **Security** tab][security]. + +Within a short time after reporting, a response will be provided and a fix will +hopefully follow. Being detailed in the initial report can help this process. + + +[security]: https://github.com/zimeg/emporia-time/security diff --git a/CHANGELOG.md b/CHANGELOG.md index 06887aa..5e0fb39 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -16,6 +16,7 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0 - Detailed information about this program is included in the README - Include the average power used over a command executation in watts - Display measurements on separate lines with the `--portable` or `-p` flags +- Documentation created for collaboration and contribution processes ### Changed diff --git a/LICENSE b/LICENSE index e3522e2..a07849b 100644 --- a/LICENSE +++ b/LICENSE @@ -1,6 +1,6 @@ MIT License -Copyright (c) 2022 Ethan Zimbelman +Copyright (c) 2022-2023 Ethan Zimbelman et al. Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the "Software"), to deal diff --git a/Makefile b/Makefile index a415d47..5b9ecb2 100644 --- a/Makefile +++ b/Makefile @@ -5,9 +5,6 @@ BIN=etime build: go build -o $(BIN) -run: build - ./$(BIN) sleep 4 - test: build go test ./... diff --git a/README.md b/README.md index 14563a5..1040ed3 100644 --- a/README.md +++ b/README.md @@ -2,6 +2,13 @@ The `time` command, with energy awareness. +**Outline**: + +- [Getting started](#getting-started) +- [Measurement information](#measurement-information) +- [Program information](#program-information) +- [Repository information](#repository-information) + ## Getting started 1. Purchase an [Emporia Smart Plug][plug] and set your device up. @@ -67,7 +74,7 @@ time. The ratio of observed-to-expected measurements is shown in the `sure` score. Lookups are repeated until a sureness greater than 80.0% is achieved. -## Command information +## Program information ### Usage guide @@ -94,7 +101,7 @@ Configurations to this program can be made using `flags` before the `command`: #### Command -The provided command can be either a program or a path to an executable. +The provided `command` can be either a program or a path to an executable. Pretty much anything that can be invoked from the command line. #### Args @@ -111,7 +118,21 @@ Environment variables can be used as another way to configure the program: - `EMPORIA_PASSWORD`: account password for Emporia - `XDG_CONFIG_HOME`: the directory to store configurations - +## Repository information + +This project is licensed under the MIT license and is not affiliated with +or endorsed by Emporia Energy. + +Documentation for the Emporia API was graciously gathered from the +[`magico13/PyEmVue`][docs] project. + +Notes on submitting contributions of any type are taken in +[`.github/CONTRIBUTING.md`][contributing]. + +Details on the processes around code for this repository are shared in the +[`.github/MAINTAINERS_GUIDE.md`][maintainers]. + + [plug]: https://www.emporiaenergy.com/emporia-smart-plug [golang]: https://go.dev/dl [dashboard]: https://web.emporiaenergy.com/#/home @@ -119,3 +140,5 @@ Environment variables can be used as another way to configure the program: [energy]: https://en.wikipedia.org/wiki/Energy [power]: https://en.wikipedia.org/wiki/Power_(physics) [docs]: https://github.com/magico13/PyEmVue/blob/master/api_docs.md +[contributing]: ./.github/CONTRIBUTING.md +[maintainers]: ./.github/MAINTAINERS_GUIDE.md