diff --git a/CODE_OF_CONDUCT.md b/CODE_OF_CONDUCT.md new file mode 100644 index 0000000..3a9e7a6 --- /dev/null +++ b/CODE_OF_CONDUCT.md @@ -0,0 +1,128 @@ +# Contributor Covenant Code of Conduct + +## Our Pledge + +We as members, contributors, and leaders pledge to make participation in our +community a harassment-free experience for everyone, regardless of age, body +size, visible or invisible disability, ethnicity, sex characteristics, gender +identity and expression, level of experience, education, socio-economic status, +nationality, personal appearance, race, religion, or sexual identity +and orientation. + +We pledge to act and interact in ways that contribute to an open, welcoming, +diverse, inclusive, and healthy community. + +## Our Standards + +Examples of behavior that contributes to a positive environment for our +community include: + +* Demonstrating empathy and kindness toward other people +* Being respectful of differing opinions, viewpoints, and experiences +* Giving and gracefully accepting constructive feedback +* Accepting responsibility and apologizing to those affected by our mistakes, + and learning from the experience +* Focusing on what is best not just for us as individuals, but for the + overall community + +Examples of unacceptable behavior include: + +* The use of sexualized language or imagery, and sexual attention or + advances of any kind +* Trolling, insulting or derogatory comments, and personal or political attacks +* Public or private harassment +* Publishing others' private information, such as a physical or email + address, without their explicit permission +* Other conduct which could reasonably be considered inappropriate in a + professional setting + +## Enforcement Responsibilities + +Community leaders are responsible for clarifying and enforcing our standards of +acceptable behavior and will take appropriate and fair corrective action in +response to any behavior that they deem inappropriate, threatening, offensive, +or harmful. + +Community leaders have the right and responsibility to remove, edit, or reject +comments, commits, code, wiki edits, issues, and other contributions that are +not aligned to this Code of Conduct, and will communicate reasons for moderation +decisions when appropriate. + +## Scope + +This Code of Conduct applies within all community spaces, and also applies when +an individual is officially representing the community in public spaces. +Examples of representing our community include using an official e-mail address, +posting via an official social media account, or acting as an appointed +representative at an online or offline event. + +## Enforcement + +Instances of abusive, harassing, or otherwise unacceptable behavior may be +reported to the community leaders responsible for enforcement by contacting +this repo owner,J onathan Zollinger. +All complaints will be reviewed and investigated promptly and fairly. + +All community leaders are obligated to respect the privacy and security of the +reporter of any incident. + +## Enforcement Guidelines + +Community leaders will follow these Community Impact Guidelines in determining +the consequences for any action they deem in violation of this Code of Conduct: + +### 1. Correction + +**Community Impact**: Use of inappropriate language or other behavior deemed +unprofessional or unwelcome in the community. + +**Consequence**: A private, written warning from community leaders, providing +clarity around the nature of the violation and an explanation of why the +behavior was inappropriate. A public apology may be requested. + +### 2. Warning + +**Community Impact**: A violation through a single incident or series +of actions. + +**Consequence**: A warning with consequences for continued behavior. No +interaction with the people involved, including unsolicited interaction with +those enforcing the Code of Conduct, for a specified period of time. This +includes avoiding interactions in community spaces as well as external channels +like social media. Violating these terms may lead to a temporary or +permanent ban. + +### 3. Temporary Ban + +**Community Impact**: A serious violation of community standards, including +sustained inappropriate behavior. + +**Consequence**: A temporary ban from any sort of interaction or public +communication with the community for a specified period of time. No public or +private interaction with the people involved, including unsolicited interaction +with those enforcing the Code of Conduct, is allowed during this period. +Violating these terms may lead to a permanent ban. + +### 4. Permanent Ban + +**Community Impact**: Demonstrating a pattern of violation of community +standards, including sustained inappropriate behavior, harassment of an +individual, or aggression toward or disparagement of classes of individuals. + +**Consequence**: A permanent ban from any sort of public interaction within +the community. + +## Attribution + +This Code of Conduct is adapted from the [Contributor Covenant][homepage], +version 2.0, available at +https://www.contributor-covenant.org/version/2/0/code_of_conduct.html. + +Community Impact Guidelines were inspired by [Mozilla's code of conduct +enforcement ladder](https://github.com/mozilla/diversity). + +[homepage]: https://www.contributor-covenant.org + +For answers to common questions about this code of conduct, see the FAQ at +https://www.contributor-covenant.org/faq. Translations are available at +https://www.contributor-covenant.org/translations. \ No newline at end of file diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md new file mode 100644 index 0000000..af8cd1e --- /dev/null +++ b/CONTRIBUTING.md @@ -0,0 +1,61 @@ +# Contributing + +By participating in this project, you agree to abide our +[code of conduct]. + +## Set up your machine + +This project is written in [java] and [micronaut] using +Oracle's [GraalVM] and uses [gradle] to +handle dependencies. + +Prerequisites: + +- [Java 21 in graal's flavor Graal (community edition)] + +clone the codebase, then cd into the repo and install the dependencies with gradle + +```sh +git clone git@github.com:JustServe-Resources/cli.git + +./gradlew assemble +``` + +## Branch off of main + +It's a good practice not to put your changes in the main branch. Branch naming conventions aren't enforced, naming my branches with a `tag`/`task` convention are suggested, similar to [Conventional Commits] naming strategy. + +See our [style guide](https://github.com/Graqr#general-styling-guide) for supported coding practices. This project enforces [Conventional Commits], which is checked with each commit. +## Test your change + +Adequate acceptance testing is to be included with pull requests for new code. See our [style guide] for our testing standards. A portion of the codebase is generated during the build process. Using gradle's `build` task will both assemble and run tests. + +```sh +./gradlew build +``` + +## Validate this builds properly +This project compiles to a native executable specific to your OS. This is different from a normal java build process. Compiling this repo into an executable is not a short process. See [graal's docs] for options like quick build mode +```sh +./gradlew nativeCompile +``` +> [!NOTE] +> This build may pass on your OS but may fail on the other OS for which this cli compiles. These will be built and tested during PR checks + + +## Submit a pull request + +Push your branch to your `cli` fork and open a pull request against the original `cli` main branch. Contributions must pass all tests and CI before merging. Clearly showcase all changes and update [tests] accordingly. + +Please only mark the pull request as "Ready for Review" when CI tests are passing and the PR is in fact complete and ready for review. + +[code of conduct]:CODE_OF_CONDUCT.md +[Conventional Commits]:https://www.conventionalcommits.org/en/v1.0.0/#summary +[GraalVM]:https://www.graalvm.org/ +[graal's docs]:https://www.graalvm.org/latest/reference-manual/native-image/optimizations-and-performance/ +[gradle]:https://docs.gradle.org/current/userguide/building_java_projects.html +[Java 21 in graal's flavor Graal (community edition)]:https://github.com/graalvm/graalvm-ce-builds/releases/ +[micronaut]:https://micronaut.io/ +[native executable]:https://www.graalvm.org/latest/reference-manual/native-image/guides/build-java-modules-into-native-executable/ +[style guide]:STYLE_GUIDE.md#testing +[tests]:STYLE_GUIDE.md \ No newline at end of file diff --git a/STYLE_GUIDE.md b/STYLE_GUIDE.md new file mode 100644 index 0000000..3cf53c2 --- /dev/null +++ b/STYLE_GUIDE.md @@ -0,0 +1,54 @@ +## General Styling Guide + +The name of the game is readability and [testability]. The following styling specifics reference Java, but are applicable to kotlin and groovy. +- Packages should be all lowercase ASCII letters. +- Classes and Interfaces should follow a mixed case (aka "camel case"), with each subsequent word's first letter capitalized + - e.g. `class TestClass` +- Follow [google's styleguide] for documentation. +- Methods should be verb-based names, and should follow a mixed case (aka "camel case") pattern, with the first letter of the first word in lower case. + - e.g. `void testMethod()` + - Braces follow the Kernighan and Ritchie style ("Egyptian brackets") for nonempty blocks and block-like constructs: + - Don't wrap a line just for the sake of not going past the 100 character marker. focus on readability. + - Variables should have meaningful names, even in lambdas. There's no shortage of space, so write readable code whose names are indicative of their use. + - Single character variable names or similar are not permitted. + - Example: + ```java + public String getReturnedResponse(Request request) { + OkHttpClient client = new OkHttpClient().newBuilder().build(); + String returnedResponse; + try (Response response = client.newCall(request).execute()) { + if (response.body() != null) { + returnedResponse = response.body().string(); + } else { + throw new RuntimeException("Body of returned response is null."); + } + } catch (IOException e) { + throw new RuntimeException(e); + } + return returnedResponse; + } + ``` + - Variables are similar to methods, in that they should follow a mixed case (aka "camel case") patter, with a + lowercase first letter. + +### Testing + +- Methods and Features are to have [adequate] unit and integration tests written before any pull request can be accepted. +- Because we use lombok, we don't need to test setters and getters. Using getters and setters is the preferred way to access class fields. +- Unit test count is to scale appropriately according to the complexity of the method. +- Features are to have [adequate] integration and end-to-end tests. +- Fixes are to have [adequate] unit, integration and end-to-end tests included with the fix for the sake of [regression testing]. +- Tests should only test one thing + - e.g. `Set store location with zip code.` + - e.g. `Fail to set store location using invalid zip code` + - e.g. `Set store location by city name` + +#### Adequate Testing Coverage +Adequate testing is determined by the method's documentation (this is why all methods require docs). Testing is surgical and specific; test exactly what is documented, no more and no less. If it's in the docs, then [test it]! The only exception to this is that [branches of code] should be covered in testing, which may not be documented. + +[adequate]:#Adequate-Testing-Coverage +[branches of code]:https://medium.com/@zubairkhansh/branch-testing-and-branch-coverage-3fb4bbd9f949 +[google's styleguide]:https://google.github.io/styleguide/javaguide.html#s7-javadoc +[regression testing]:https://www.browserstack.com/guide/regression-testing +[test it]:https://www.geeksforgeeks.org/software-engineering/difference-between-positive-testing-and-negative-testing/ +[testability]:#Adequate-Testing-Coverage \ No newline at end of file