DOC: Updated Contributing.md file and version update script (#24)

eBay · Dec 4, 2024 · 3199280 · 3199280
2 parents 7ef61b0 + 0e7cbd1
commit 3199280
Show file tree

Hide file tree

Showing 12 changed files with 261 additions and 102 deletions.
diff --git a/.github/CONTRIBUTING.md b/.github/CONTRIBUTING.md
@@ -6,7 +6,7 @@ Thank you so much for wanting to contribute to eJMask! Here are a few important
 2. Pull requests are great for small fixes for bugs, documentation, etc.
 3. Code contributions require updating relevant documentation.
 
-This project takes all contributions through [pull requests](https://help.github.com/articles/using-pull-requests). Code should *not* be pushed directly to `master`.
+This project takes all contributions through [pull requests][pull-request-blog]. Code should *not* be pushed directly to `master`.
 
 The following guidelines apply to all contributors.
 
@@ -22,7 +22,61 @@ All types of contributions, from minor documentation changes to new capabilities
 * Submit a pull request to the repository.
 * Update the `eJMask` GitHub issue with the generated pull request link.
 
-## General Guidelines
+### Git Workflow
+
+1. Go to GitHub and fork the repository [ebay/ejmask][fork-repo].
+2. Clone your fork to your local workspace:
+    ```commandline
+    git clone [email protected]:<user-name>/ejmask.git
+    ```
+3. Create a new [feature branch][create-branch].
+4. Make your changes, perform a self-review, build, and test.
+5. Push your changes to the [remote fork][push-commits].
+6. Raise a [pull request][create-pr].
+
+```mermaid
+stateDiagram-v2
+    state upstream <<join>>
+    state fork_state <<join>>
+    state local_state <<join>>
+    note left of upstream
+        ebay/ejmask
+    end note
+    upstream --> fork_state: fork
+    note left of fork_state
+        {user-name}/ejmask
+    end note
+    fork_state --> local_state: checkout
+    note right of local_state
+        impl/new_feature
+    end note
+    state FeatureDev {
+        local_state --> SelfReview : build test
+        local_state --> local_state: commit
+        SelfReview --> SelfReview: lint
+        SelfReview --> local_state: fix
+    }
+    local_state --> fork_state: push
+    fork_state --> local_state: fetch
+    fork_state --> Draft: pull_request
+    state PullRequest {
+        Draft --> ReadyToReview
+        Draft --> Draft: Self review
+        ReadyToReview --> ReadyToReview: Peer review
+        ReadyToReview --> Approved
+    }
+    Approved --> upstream: merge
+    upstream --> fork_state: pull 
+```
+> Please keep your branch up to date by [rebasing][rebase-git] upstream changes from the develop branch.
+
+## Development
+### Pre-requisites
+- JDK 8
+- Maven 3.6.3
+- python3 (for development scripts)
+
+### General Guidelines
 
 * Only one logical change per commit.
 * Do not mix whitespace changes with functional code changes.
@@ -36,15 +90,17 @@ All types of contributions, from minor documentation changes to new capabilities
 * The project already has good test coverage, so look at some of the existing tests if you're unsure how to go about it.
 * Please squash all commits for a change into a single commit (this can be done using `git rebase -i`).
 
-## Commit Message Guidelines
-
-* Provide a brief description of the change in the first line.
-* Insert a single blank line after the first line.
-* Provide a detailed description of the change in the following lines, breaking paragraphs where needed.
-* The first line should be limited to 50 characters and should not end in a period.
-* Subsequent lines should be wrapped at 72 characters.
+### Versioning
+* We are using [Semantic Versioning](https://semver.org/). 
+* We are following the format `MAJOR.MINOR.PATCH`.
+  * `MAJOR` : fundamental changes.
+  * `MINOR` : incompatible changes.
+  * `PATCH` : backward-compatible changes & bug fixes.
+* Use `version_update.py` to update the version in the `pom.xml` file.
+* Use snapshot versions for development & testing 
+* Update the version to release when you commit. 
 
-## Java Guidelines
+### Java Guidelines
 
 - Please make sure:
   * Source code is always formatted before commit.
@@ -54,3 +110,37 @@ All types of contributions, from minor documentation changes to new capabilities
   * Trailing whitespace on all lines.
   * All unused imports.
   * Empty blocks.
+
+### Build
+```shell
+mvn clean install --settings settings.xml --batch-mode
+```
+
+### Commit Message Guidelines
+* 
+* Provide a brief description of the change in the first line.
+* Insert a single blank line after the first line.
+* Provide a detailed description of the change in the following lines, breaking paragraphs where needed.
+* The first line should be limited to 50 characters and should not end in a period.
+* Subsequent lines should be wrapped at 72 characters.
+
+## Pull Request Guidelines
+
+- Ensure the pull request has a description of the change.
+- Ensure the pull request has a proper title describing the change.
+  - Prefix the title with:
+    - `IMPL` for a new change.
+    - `FIX` for a bug fix.
+    - `DOC` for a documentation change.
+    - `DEV` for refactoring.
+  - For `IMPL` and non-compatible refactoring or bug fixes, increment the version to the next major (e.g., `1.0.0` -> `1.1.0`).
+  - For all other changes, increment the minor version (e.g., `1.0.0` -> `1.0.1`).
+    > eg: DEV: Refactored the code to use a new pattern builder
+
+[create-branch]: https://docs.github.com/en/pull-requests/collaborating-with-pull-requests/proposing-changes-to-your-work-with-pull-requests/creating-and-deleting-branches-within-your-repository
+[create-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
+[clone-repo]: https://docs.github.com/en/repositories/creating-and-managing-repositories/cloning-a-repository
+[fork-repo]: https://docs.github.com/en/pull-requests/collaborating-with-pull-requests/working-with-forks/fork-a-repo
+[push-commits]: https://docs.github.com/en/get-started/using-git/pushing-commits-to-a-remote-repository
+[pull-request-blog]: https://help.github.com/articles/using-pull-requests
+[rebase-git]: https://docs.github.com/en/get-started/using-git/about-git-rebase
diff --git a/README.md b/README.md
@@ -228,19 +228,19 @@ You can download source and binaries from our [release page](https://github.com/
 Alternatively you can pull it from the central Maven repositories:
 
 ### Using in your maven project.
-
+> Please check the release version before adding to your project.
 ```xml
 <dependency>
   <groupId>com.ebay.ejmask</groupId>
   <artifactId>ejmask-bom</artifactId>
-  <version>1.1.0</version>
+  <version>2.0.0</version>
 </dependency>
 ```
 
 ### Using in your Gradle Project.
 
 ```groovy
-compile group: 'com.ebay.ejmask', name: 'ejmask-bom', version: '1.1.0'
+compile group: 'com.ebay.ejmask', name: 'ejmask-bom', version: '2.0.0'
 ```
 
 ## Roadmap

diff --git a/ejmask-api/pom.xml b/ejmask-api/pom.xml
@@ -4,7 +4,7 @@
     <parent>
         <groupId>com.ebay.ejmask</groupId>
         <artifactId>ejmask-parent</artifactId>
-        <version>1.2.0-SNAPSHOT</version>
+        <version>${revision}${changelist}</version>
     </parent>
 
     <artifactId>ejmask-api</artifactId>

diff --git a/ejmask-bom/pom.xml b/ejmask-bom/pom.xml
@@ -4,7 +4,7 @@
     <parent>
         <groupId>com.ebay.ejmask</groupId>
         <artifactId>ejmask-parent</artifactId>
-        <version>1.2.0-SNAPSHOT</version>
+        <version>${revision}${changelist}</version>
         <relativePath>../pom.xml</relativePath>
     </parent>
 

diff --git a/ejmask-core/pom.xml b/ejmask-core/pom.xml
@@ -4,7 +4,7 @@
     <parent>
         <groupId>com.ebay.ejmask</groupId>
         <artifactId>ejmask-parent</artifactId>
-        <version>1.2.0-SNAPSHOT</version>
+        <version>${revision}${changelist}</version>
     </parent>
 
     <artifactId>ejmask-core</artifactId>

diff --git a/ejmask-extensions/pom.xml b/ejmask-extensions/pom.xml
@@ -4,7 +4,7 @@
     <parent>
         <groupId>com.ebay.ejmask</groupId>
         <artifactId>ejmask-parent</artifactId>
-        <version>1.2.0-SNAPSHOT</version>
+        <version>${revision}${changelist}</version>
     </parent>
 
     <artifactId>ejmask-extensions</artifactId>

diff --git a/ejmask-spring/ejmask-spring-autoconfig/pom.xml b/ejmask-spring/ejmask-spring-autoconfig/pom.xml
@@ -4,7 +4,7 @@
     <parent>
         <groupId>com.ebay.ejmask</groupId>
         <artifactId>ejmask-spring</artifactId>
-        <version>1.2.0-SNAPSHOT</version>
+        <version>${revision}${changelist}</version>
     </parent>
 
     <artifactId>ejmask-spring-autoconfig</artifactId>

diff --git a/ejmask-spring/ejmask-spring-boot/pom.xml b/ejmask-spring/ejmask-spring-boot/pom.xml
@@ -4,7 +4,7 @@
     <parent>
         <groupId>com.ebay.ejmask</groupId>
         <artifactId>ejmask-spring</artifactId>
-        <version>1.2.0-SNAPSHOT</version>
+        <version>${revision}${changelist}</version>
     </parent>
 
     <artifactId>ejmask-spring-boot</artifactId>

diff --git a/ejmask-spring/ejmask-spring-core/pom.xml b/ejmask-spring/ejmask-spring-core/pom.xml
@@ -4,7 +4,7 @@
     <parent>
         <groupId>com.ebay.ejmask</groupId>
         <artifactId>ejmask-spring</artifactId>
-        <version>1.2.0-SNAPSHOT</version>
+        <version>${revision}${changelist}</version>
     </parent>
 
     <artifactId>ejmask-spring-core</artifactId>

diff --git a/ejmask-spring/pom.xml b/ejmask-spring/pom.xml
@@ -4,7 +4,7 @@
     <parent>
         <groupId>com.ebay.ejmask</groupId>
         <artifactId>ejmask-parent</artifactId>
-        <version>1.2.0-SNAPSHOT</version>
+        <version>${revision}${changelist}</version>
     </parent>
 
     <artifactId>ejmask-spring</artifactId>
@@ -15,17 +15,4 @@
         <module>ejmask-spring-boot</module>
         <module>ejmask-spring-autoconfig</module>
     </modules>
-
-    <dependencyManagement>
-        <!-- Limit usage of external lib as much as possible -->
-        <dependencies>
-            <dependency>
-                <groupId>org.springframework.boot</groupId>
-                <artifactId>spring-boot-dependencies</artifactId>
-                <version>2.7.4</version>
-                <scope>import</scope>
-                <type>pom</type>
-            </dependency>
-        </dependencies>
-    </dependencyManagement>
 </project>
diff --git a/pom.xml b/pom.xml
@@ -4,7 +4,7 @@
 
     <groupId>com.ebay.ejmask</groupId>
     <artifactId>ejmask-parent</artifactId>
-    <version>1.2.0-SNAPSHOT</version>
+    <version>${revision}${changelist}</version>
 
     <packaging>pom</packaging>
 
@@ -27,6 +27,8 @@
         <project.build.sourceEncoding>UTF-8</project.build.sourceEncoding>
         <maven.compiler.target>1.8</maven.compiler.target>
         <maven.compiler.source>1.8</maven.compiler.source>
+        <revision>1.2.0</revision>
+        <changelist></changelist>
     </properties>
 
     <scm>