Encourage community collaboration and contributions (#36)

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

.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].
+
+<!-- a collection of links -->
+[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

.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.
+
+<!-- a collection of links -->
+[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

.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.
+
+<!-- a collection of links -->
+[security]: https://github.com/zimeg/emporia-time/security

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
 

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

Makefile

@@ -5,9 +5,6 @@ BIN=etime
 build:
 	go build -o $(BIN)
 
-run: build
-	./$(BIN) sleep 4
-
 test: build
 	go test ./...
 

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,11 +118,27 @@ 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
 
-<!-- links -->
+## 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].
+
+<!-- a collection of links -->
 [plug]: https://www.emporiaenergy.com/emporia-smart-plug
 [golang]: https://go.dev/dl
 [dashboard]: https://web.emporiaenergy.com/#/home
 [time]: https://stackoverflow.com/a/556411
 [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