From 71431332f4760a2cde691eebf99a28ea92743ed5 Mon Sep 17 00:00:00 2001 From: jonathan zollinger Date: Tue, 10 Oct 2023 11:51:33 -0600 Subject: [PATCH] feature(docs): add Contributing doc --- Contributing.md | 60 +++++++++++++++++++++++++ Style Guide.md | 114 ------------------------------------------------ 2 files changed, 60 insertions(+), 114 deletions(-) create mode 100644 Contributing.md delete mode 100644 Style Guide.md diff --git a/Contributing.md b/Contributing.md new file mode 100644 index 0000000..2b02213 --- /dev/null +++ b/Contributing.md @@ -0,0 +1,60 @@ +# Contributing + +By participating in this project, you agree to abide our +[code of conduct](CODE_OF_CONDUCT.md). + +## Set up your machine + +`tarvester` is written in [Java](https://www.azul.com/modern-cloud-enterprise/) using Oracle's [GraalVM](https://github.com/oracle/graal) and uses [Maven](https://maven.apache.org/what-is-maven.html) to handle dependencies. + +Prerequisites: + +- [Java 17.0.8](https://sdkman.io/jdks#graalvm) in graal's flavor Graal (community edition) +- [Maven 3.8.6](https://maven.apache.org/install.html) + +Other things you might need to run the tests: + +- [Docker](https://www.docker.com/) + +[//]: # (TODO: add docker configuration) + +Create your own fork of `tarvester`, then clone your fork anywhere: + +```shell +git clone git@github.com:/tarvester.git +``` + +`cd` into the directory and install the dependencies: + +```shell +mvn clean compile +``` + +## Branch off of main + +It's a good practice not to put your changes in the main branch. Branch naming conventions aren't enforced, but I +personally like naming my branches with a `tag`/`task` convention. See [Create a commit](#create-a-commit). + +See our [style guide](StyleGuide.md) for supported coding practices. +## Test your change + +Adequate acceptance testing is to be included with pull requests for new code. See our [style guide](StyleGuide.md#Testing) for our testing standards. + +```sh +mvn clean test +``` + +## Validate `tarvester` builds + +```sh +mvn clean install +``` + + +## Create a commit + +Commit messages should be well formatted and conform to [Conventional Commits](https://www.conventionalcommits.org). + +## Submit a pull request + +Push your branch to your `tarvester` fork and open a pull request against the original `tarvester` main branch. diff --git a/Style Guide.md b/Style Guide.md deleted file mode 100644 index ad25452..0000000 --- a/Style Guide.md +++ /dev/null @@ -1,114 +0,0 @@ -## General Styling Guide - -- 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` -- Methods should be verbs, 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: - - Dont wrap a line just for the sake of not going past the 100 character marker, especially if wrapping makes it harder to read. - - Variables should have meaningful names, even in lambdas. There's no shortage of space, so write readable, self-documenting code. - - Single character variable names or similar are not permitted. - - Example: - ```java - public String getReturnedResponse(Request request) { - OkHttpClient client = new OkHttpClient().newBuilder().build(); - String returnedResponse = null; - 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. - - Constants should be all uppercase, with underscores replacing spaces. - - e.g. `int MAX_RETRY_COUNT = 5;` - -## Coding Standards - -### Testing - -- Methods and Features are to have adequate unit and integration tests written before any pull request can be accepted. -- Methods such as setters and getters are to have atleast one negative and one standard unit test. -- Unit test count is to scale appropriately according to the complexity of the method. -- Features are to have appropriate integration and end to end tests. -- Fixes are to have appropriate 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` -- Selenium code should use the Page Object Model making each page a class - - Use inheritance to pull in common variables and methods for your product - - The top of the class should contain web elements - - Inside the class should contain methods that do one thing with JavaDoc - - e.g. - ```java - /** - * method triggers click event on New Setting selection to access the Edit Setting Definition - * pop-up window - * @return returns new instance of inner class clickNewSetting in order to select OK and - * cancel buttons in this pop-up window - */ - def clickNewSetting() { - newSettingElement.click() - return new clickNewSetting(driver) - } - - /** - * Inner Class provides methods to select OK or Cancel in the Edit Setting Definition pop-up window - */ - private class clickNewSetting extends CreateConnectorSharedTabs.newSetting { - private @FindBy(id = 'saveButton') WebElement editSettingOkButton - private @FindBy(id = 'cancelButton') WebElement editSettingCancelButton - - clickNewSetting(WebDriver driver) { - super(driver) - } - - /** - * method triggers click event on OK button - * @return returns instance of main Desktop tab - */ - def clickOK() { - editSettingOkButton.click() - log.info("Clicked Edit Setting Definition OK button") - return new openDesktopTab(driver) - } - - /** - * method triggers click event on Cancel button - * @return returns instance of main Desktop tab - */ - def clickCancel() { - editSettingCancelButton.click() - log.info("Clicked Edit Setting Definition Cancel button") - return new openDesktopTab(driver) - } - } - ``` - -- Selenium Web Programs - - Tests should be made up of methods, and logic (such as loops) should be in a utils class - - Each test class should inherit from either a UI base test or a REST base test - - A test should never call another test. - - Helper methods should go in a utils class (when possible the Util should be a java class) - - e.g. Web Test - ```java - @Test - void changeStoreLocation(){ - new StoreLogin() - .clickStoreBanner() - .addNextZipCode() - .clickSubmit - } - ``` \ No newline at end of file