Skip to content

Commit 12aaabf

Browse files
devondragondevondragon
authored
Update CONTRIBUTING.md
Updated and improved.
1 parent fb7e56b commit 12aaabf

1 file changed

Lines changed: 117 additions & 171 deletions

File tree

‎CONTRIBUTING.md‎

Lines changed: 117 additions & 171 deletions
Original file line numberDiff line numberDiff line change
@@ -1,232 +1,178 @@
11
# Contributing to SpringUserFramework
22

3-
Thank you for considering contributing to SpringUserFramework! We appreciate your time and effort in improving our project. The following guidelines will help you navigate the contribution process.
3+
Thank you for considering contributing to **SpringUserFramework**, a Spring Boot library designed to simplify user management and authentication. Whether you're fixing bugs, building new features, or improving documentation, your contributions are welcome and appreciated.
44

5-
## Table of Contents
5+
This guide covers how to set up your local environment, contribute to both the library and the companion demo app, and submit high-quality pull requests.
6+
7+
---
68

9+
## Table of Contents
710
- [Code of Conduct](#code-of-conduct)
8-
- [Getting Started](#getting-started)
9-
- [Forking the Repository](#forking-the-repository)
10-
- [Cloning Your Fork](#cloning-your-fork)
11-
- [Setting Up the Upstream Remote](#setting-up-the-upstream-remote)
11+
- [Prerequisites](#prerequisites)
12+
- [Project Structure](#project-structure)
13+
- [Forking and Cloning](#forking-and-cloning)
1214
- [Working on Issues](#working-on-issues)
13-
- [Creating a Feature Branch](#creating-a-feature-branch)
14-
- [Making Changes](#making-changes)
15-
- [Committing Changes](#committing-changes)
16-
- [Pushing Changes](#pushing-changes)
17-
- [Submitting a Pull Request](#submitting-a-pull-request)
15+
- [Branching and Development Workflow](#branching-and-development-workflow)
16+
- [Testing Your Changes](#testing-your-changes)
17+
- [Writing Unit Tests](#writing-unit-tests)
1818
- [Code Style and Standards](#code-style-and-standards)
19-
- [Testing](#testing)
20-
- [Documentation](#documentation)
19+
- [Submitting a Pull Request](#submitting-a-pull-request)
20+
- [Providing Easy Integration Steps](#providing-easy-integration-steps)
2121
- [Community Support](#community-support)
2222

23+
---
24+
2325
## Code of Conduct
26+
We expect all contributors to follow our [Code of Conduct](CODE_OF_CONDUCT.md). Be respectful and inclusive.
2427

25-
Please note that this project is released with a [Contributor Code of Conduct](CODE_OF_CONDUCT.md). By participating in this project, you agree to abide by its terms.
28+
---
2629

27-
## Getting Started
30+
## Prerequisites
31+
Before starting development, make sure you have the following installed:
2832

29-
### Forking the Repository
33+
- JDK 17 or later
34+
- Gradle
35+
- Maven
36+
- Git
37+
- Docker (optional for demo app DB)
38+
- IntelliJ IDEA or VSCode (recommended — the maintainer uses VSCode)
3039

31-
To contribute to SpringUserFramework, begin by forking the repository to your GitHub account. This creates a personal copy of the project where you can make changes without affecting the original repository.
40+
---
3241

33-
1. Navigate to the [SpringUserFramework repository](https://github.com/devondragon/SpringUserFramework/).
34-
2. Click the "Fork" button in the upper right corner.
42+
## Project Structure
43+
- **SpringUserFramework** – The main Spring Boot library.
44+
- **SpringUserFrameworkDemoApp** – A companion frontend/demo application used to test and showcase library features. [GitHub Link](https://github.com/devondragon/SpringUserFrameworkDemoApp)
3545

36-
### Cloning Your Fork
46+
---
3747

38-
Next, clone your fork to your local machine to start making changes.
48+
## Forking and Cloning
49+
1. **Fork both repositories:**
50+
- [SpringUserFramework](https://github.com/devondragon/SpringUserFramework)
51+
- [SpringUserFrameworkDemoApp](https://github.com/devondragon/SpringUserFrameworkDemoApp)
3952

53+
2. **Clone locally:**
4054
```bash
4155
git clone https://github.com/your-username/SpringUserFramework.git
42-
cd SpringUserFramework
56+
git clone https://github.com/your-username/SpringUserFrameworkDemoApp.git
4357
```
4458

45-
46-
### Setting Up the Upstream Remote
47-
48-
To keep your fork synchronized with the original repository, add it as an upstream remote:
49-
59+
3. **Add upstream remotes:**
5060
```bash
61+
cd SpringUserFramework
5162
git remote add upstream https://github.com/devondragon/SpringUserFramework.git
52-
```
5363

64+
cd ../SpringUserFrameworkDemoApp
65+
git remote add upstream https://github.com/devondragon/SpringUserFrameworkDemoApp.git
66+
```
5467

55-
This setup allows you to fetch updates from the main repository and incorporate them into your fork.
68+
---
5669

5770
## Working on Issues
71+
1. Check the [Issues](https://github.com/devondragon/SpringUserFramework/issues) tab.
72+
2. Comment to claim an issue.
73+
3. Sync your fork and create a new branch off the target branch:
74+
```bash
75+
git fetch upstream
76+
git checkout -b feature/my-change upstream/branch-name
77+
```
5878

59-
We use GitHub Issues to track bugs and feature requests. Before starting work, please check existing issues to avoid duplication.
60-
61-
1. Browse the [Issues](https://github.com/devondragon/SpringUserFramework/issues) to find something you'd like to work on.
62-
2. Comment on the issue to let others know you're working on it.
63-
64-
### Creating a Feature Branch
65-
66-
For each issue, create a new branch in your local repository. This keeps your changes organized and makes it easier to manage multiple contributions.
67-
68-
1. Fetch the latest changes from the upstream repository:
69-
70-
```bash
71-
git fetch upstream
72-
```
73-
74-
75-
2. Check out the branch associated with the issue:
76-
77-
```bash
78-
git checkout upstream/branch-name
79-
```
80-
81-
82-
3. Create a new branch off of the issue branch:
83-
84-
```bash
85-
git checkout -b your-feature-branch
86-
```
87-
88-
89-
### Making Changes
90-
91-
Make your desired changes in your local repository. Ensure that your code adheres to the project's coding standards and includes appropriate documentation.
92-
93-
### Committing Changes
94-
95-
Commit your changes with clear and descriptive messages.
79+
---
9680

81+
## Branching and Development Workflow
82+
1. Work on your feature or fix in a branch.
83+
2. Make clear, well-scoped commits. Use [Conventional Commits](https://www.conventionalcommits.org/).
84+
3. Push to your fork:
9785
```bash
98-
git add .
99-
git commit -m "Brief description of your changes"
86+
git push origin feature/my-change
10087
```
10188

89+
> **Note:** Please do not commit or push changes to the version number in `gradle.properties` or any release metadata. Version management is handled by the project maintainer.
10290
103-
Follow the [Conventional Commits](https://www.conventionalcommits.org/) specification for commit messages.
91+
---
10492

105-
### Pushing Changes
106-
107-
Push your feature branch to your fork on GitHub:
93+
## Testing Your Changes
94+
Since this is a library, you’ll want to test changes via the **Demo App**:
10895

96+
### Steps:
97+
1. **Build and publish the library locally:**
10998
```bash
110-
git push origin your-feature-branch
99+
cd SpringUserFramework
100+
./gradlew publishToMavenLocal
111101
```
112102

103+
2. **Update the dependency in the demo app:**
104+
```groovy
105+
// In SpringUserFrameworkDemoApp/build.gradle
106+
dependencies {
107+
implementation 'com.yourgroupid:spring-user-framework:1.2.3-SNAPSHOT'
108+
}
109+
```
113110

111+
3. **Run the demo app:**
112+
```bash
113+
cd ../SpringUserFrameworkDemoApp
114+
./gradlew bootRun
115+
```
114116

115-
## Unit Tests and Test Coverage
116-
117-
All contributions to `SpringUserFramework` **must include appropriate unit tests**. This ensures that the library remains stable, reliable, and maintainable as it grows.
118-
119-
### Requirements
120-
121-
- **All new features** must include unit tests that thoroughly cover the new functionality.
122-
- **Bug fixes** should include tests that demonstrate the issue and confirm the fix.
123-
- If you are **modifying existing code**, you should update or expand the relevant tests to reflect those changes.
124-
- **All tests must pass** before a pull request will be considered for merging.
117+
### Optional: Setup DB with Docker
118+
```bash
119+
cd SpringUserFrameworkDemoApp
120+
docker-compose up -d
121+
```
125122

126-
### Running Tests Locally
123+
---
127124

128-
Before submitting a PR, run the full test suite to ensure your changes do not introduce regressions:
125+
## Writing Unit Tests
126+
All PRs must include appropriate tests:
127+
- New features must include unit tests.
128+
- Bug fixes should include regression tests.
129+
- Modified code should have updated tests.
129130

131+
### Run all tests:
130132
```bash
131133
./gradlew test
132134
```
133135

134-
If you are using an IDE like VSCode or IntelliJ, you can also run the tests from the IDE directly.
135-
136-
We may add code coverage reporting tools in the future to help enforce this, but for now, maintainers will review tests as part of the code review process.
137-
138-
139-
## Submitting a Pull Request
140-
141-
Once your changes are pushed to your fork, submit a pull request (PR) to the original repository:
142-
143-
1. Navigate to your fork on GitHub.
144-
2. Click the "Compare & pull request" button next to your feature branch.
145-
3. Ensure the base fork is `devondragon/SpringUserFramework` and the base branch is the issue branch you're addressing.
146-
4. Provide a clear title and description for your PR, referencing the issue number it addresses.
147-
5. Click "Create pull request."
148-
149-
Your PR will be reviewed by the maintainers. Please be responsive to feedback and willing to make adjustments as needed.
150-
151-
152-
## Contributing to the Demo Frontend
153-
154-
If your change involves a **frontend component**, or if it requires a user interface to **showcase or test the functionality** (such as login flows, authentication UIs, or session behavior), you'll also need to contribute to the companion frontend project:
155-
👉 [**SpringUserFrameworkDemoApp**](https://github.com/devondragon/SpringUserFrameworkDemoApp)
156-
157-
This project is a lightweight web application used to **demonstrate and test** features of the `SpringUserFramework` library.
158-
159-
### What You Need to Do
160-
161-
1. **Fork the `SpringUserFrameworkDemoApp` repository** as well.
162-
2. Make changes or add test pages in the demo app to support or demonstrate your backend work.
163-
3. Submit a separate pull request to the `SpringUserFrameworkDemoApp` repository.
164-
4. Reference your demo app PR in your main `SpringUserFramework` pull request description, so reviewers can test your changes end-to-end.
165-
166-
Keeping the demo app up to date with relevant examples helps others understand how to use the library and ensures that all features are properly tested in a real-world scenario.
167-
136+
PRs without passing tests will not be accepted.
168137

138+
---
169139

170-
## Testing Local Changes with the Demo App
171-
172-
Since `SpringUserFramework` is a **library**, the best way to test your changes is by using the companion project:
173-
👉 [**SpringUserFrameworkDemoApp**](https://github.com/devondragon/SpringUserFrameworkDemoApp)
174-
175-
This demo app allows you to see how the library behaves in a real application context.
176-
177-
### How to Test Your Changes Locally
178-
179-
To test updates to the library before submitting a pull request, follow these steps:
180-
181-
1. **Install Maven (if not already installed)**
182-
You'll need Maven installed locally because Gradle publishes the library into your **local Maven cache**.
183-
184-
2. **Build and publish the library locally**
185-
In your fork of `SpringUserFramework`, run:
186-
187-
```bash
188-
./gradlew publishToMavenLocal
189-
```
190-
191-
This will compile the project and publish it as a `.jar` file with a `-SNAPSHOT` version into your local Maven cache (usually located at `~/.m2/repository`).
192-
193-
3. **Update the demo app to use your local library**
194-
In your fork of [`SpringUserFrameworkDemoApp`](https://github.com/devondragon/SpringUserFrameworkDemoApp):
195-
196-
- Open `build.gradle`.
197-
- Update the library dependency to match the `SNAPSHOT` version defined in the `gradle.properties` file from your local library project.
198-
199-
Example:
200-
```groovy
201-
implementation 'com.yourgroupid:spring-user-framework:1.2.3-SNAPSHOT'
202-
```
140+
## Code Style and Standards
141+
- Follow the [Google Java Style Guide](https://google.github.io/styleguide/javaguide.html).
142+
- Use meaningful variable/method names.
143+
- Keep commits focused and easy to understand.
203144

204-
4. **Build and run the demo app**
205-
Use your IDE or run from the command line:
145+
---
206146

207-
```bash
208-
./gradlew bootRun
209-
```
147+
## Submitting a Pull Request
148+
1. Push your feature branch to your fork.
149+
2. Open a PR against the appropriate feature or development branch in the original repo.
150+
3. Include:
151+
- A clear description
152+
- Related issue number(s)
153+
- Reference to the related DemoApp PR (if applicable)
154+
4. Respond to feedback and revise as needed.
210155

211-
The demo app should now load and use your locally built version of the library. This allows you to interactively test your changes before pushing them upstream.
156+
---
212157

213-
> 💡 Make sure not to commit any version changes to `build.gradle` or `gradle.properties` as the project maintainer is the only one to update versions.
158+
## Providing Easy Integration Steps
159+
If you're adding support for an integration, third-party tool, or external service:
214160

161+
- Please ensure your PR includes **clear, step-by-step instructions** on how to set up and test the new integration.
162+
- These steps should be easy to follow for both the maintainer and new users trying the feature.
163+
- Add any required configuration to the README or relevant config files.
215164

216-
## Code Style and Standards
165+
The goal is to make it simple to verify and adopt your contribution without digging through code or documentation.
217166

218-
Please adhere to the following coding standards:
167+
---
219168

220-
- Follow the [Google Java Style Guide](https://google.github.io/styleguide/javaguide.html) for Java code.
221-
- Use meaningful variable and method names.
222-
- Write concise and clear comments where necessary.
169+
## Community Support
170+
If you need help while contributing:
223171

224-
Consistent code style helps maintain readability and ease of maintenance.
172+
- Open an [Issue](https://github.com/devondragon/SpringUserFramework/issues) or a [Discussion](https://github.com/devondragon/SpringUserFramework/discussions).
173+
- Tag **@devondragon** in the comments if you’re stuck or need guidance.
174+
- We’re happy to help clarify workflows or provide feedback on early ideas.
225175

226-
## Testing
176+
Thank you for helping us make this project better!
227177

228-
Ensure that your changes do not break existing tests and include new tests as appropriate. Run all tests before submitting a PR:
229-
230-
```bash
231-
./gradlew test
232-
```
178+
---

0 commit comments

Comments
 (0)