Skip to content

Commit fb7e56b

Browse files
devondragondevondragon
authored
Merge pull request #168 from devondragon/devondragon-contributing-guide
Devondragon contributing guide
2 parents 186ad61 + e5d4aec commit fb7e56b

3 files changed

Lines changed: 312 additions & 0 deletions

File tree

‎CODE_OF_CONDUCT.md‎

Lines changed: 73 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,73 @@
1+
# Contributor Covenant Code of Conduct
2+
3+
## Our Pledge
4+
5+
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.
6+
7+
We pledge to act and interact in ways that contribute to an open, welcoming, diverse, inclusive, and healthy community.
8+
9+
## Our Standards
10+
11+
Examples of behavior that contributes to a positive environment include:
12+
13+
- Demonstrating empathy and kindness toward other people
14+
- Being respectful of differing opinions, viewpoints, and experiences
15+
- Giving and gracefully accepting constructive feedback
16+
- Accepting responsibility and apologizing to those affected by our mistakes, and learning from the experience
17+
- Focusing on what is best not just for us as individuals, but for the overall community
18+
19+
Examples of unacceptable behavior include:
20+
21+
- The use of sexualized language or imagery, and sexual attention or advances of any kind
22+
- Trolling, insulting or derogatory comments, and personal or political attacks
23+
- Public or private harassment
24+
- Publishing others’ private information, such as a physical or email address, without their explicit permission
25+
- Other conduct which could reasonably be considered inappropriate in a professional setting
26+
27+
## Enforcement Responsibilities
28+
29+
Project maintainers are responsible for clarifying and enforcing our standards of acceptable behavior and will take appropriate and fair corrective action in response to any behavior they deem inappropriate, threatening, offensive, or harmful.
30+
31+
Project maintainers 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.
32+
33+
## Scope
34+
35+
This Code of Conduct applies within all project spaces, and also applies when an individual is officially representing the project in public spaces.
36+
37+
Examples include using an official project email address, posting via an official social media account, or acting as an appointed representative at an online or offline event.
38+
39+
## Enforcement
40+
41+
Instances of abusive, harassing, or otherwise unacceptable behavior may be reported to the project maintainers at **devon@digitalsanctuary.com**.
42+
All complaints will be reviewed and investigated promptly and fairly.
43+
44+
All project maintainers are obligated to respect the privacy and security of the reporter of any incident.
45+
46+
## Enforcement Guidelines
47+
48+
Project maintainers will follow these Community Impact Guidelines in determining the consequences for any action they deem in violation of this Code of Conduct:
49+
50+
### 1. Correction
51+
**Impact**: Use of inappropriate language or other behavior deemed unprofessional or unwelcome.
52+
**Consequence**: A private, written warning from project maintainers, providing clarity around the nature of the violation and an explanation of why the behavior was inappropriate. A public apology may be requested.
53+
54+
### 2. Warning
55+
**Impact**: A violation through a single incident or series of actions.
56+
**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.
57+
58+
### 3. Temporary Ban
59+
**Impact**: A serious violation of community standards, including sustained inappropriate behavior.
60+
**Consequence**: A temporary ban from any sort of interaction or public communication with the community for a specified period of time.
61+
62+
### 4. Permanent Ban
63+
**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.
64+
**Consequence**: A permanent ban from any sort of public interaction within the project community.
65+
66+
## Attribution
67+
68+
This Code of Conduct is adapted from the [Contributor Covenant][homepage], version 2.1, available at
69+
[https://www.contributor-covenant.org/version/2/1/code_of_conduct.html](https://www.contributor-covenant.org/version/2/1/code_of_conduct.html)
70+
71+
For answers to common questions about this code of conduct, see
72+
[https://www.contributor-covenant.org/faq](https://www.contributor-covenant.org/faq)
73+
Translations are available at [https://www.contributor-covenant.org/translations](https://www.contributor-covenant.org/translations)

‎CONTRIBUTING.md‎

Lines changed: 232 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,232 @@
1+
# Contributing to SpringUserFramework
2+
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.
4+
5+
## Table of Contents
6+
7+
- [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)
12+
- [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)
18+
- [Code Style and Standards](#code-style-and-standards)
19+
- [Testing](#testing)
20+
- [Documentation](#documentation)
21+
- [Community Support](#community-support)
22+
23+
## Code of Conduct
24+
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.
26+
27+
## Getting Started
28+
29+
### Forking the Repository
30+
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.
32+
33+
1. Navigate to the [SpringUserFramework repository](https://github.com/devondragon/SpringUserFramework/).
34+
2. Click the "Fork" button in the upper right corner.
35+
36+
### Cloning Your Fork
37+
38+
Next, clone your fork to your local machine to start making changes.
39+
40+
```bash
41+
git clone https://github.com/your-username/SpringUserFramework.git
42+
cd SpringUserFramework
43+
```
44+
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+
50+
```bash
51+
git remote add upstream https://github.com/devondragon/SpringUserFramework.git
52+
```
53+
54+
55+
This setup allows you to fetch updates from the main repository and incorporate them into your fork.
56+
57+
## Working on Issues
58+
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.
96+
97+
```bash
98+
git add .
99+
git commit -m "Brief description of your changes"
100+
```
101+
102+
103+
Follow the [Conventional Commits](https://www.conventionalcommits.org/) specification for commit messages.
104+
105+
### Pushing Changes
106+
107+
Push your feature branch to your fork on GitHub:
108+
109+
```bash
110+
git push origin your-feature-branch
111+
```
112+
113+
114+
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.
125+
126+
### Running Tests Locally
127+
128+
Before submitting a PR, run the full test suite to ensure your changes do not introduce regressions:
129+
130+
```bash
131+
./gradlew test
132+
```
133+
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+
168+
169+
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+
```
203+
204+
4. **Build and run the demo app**
205+
Use your IDE or run from the command line:
206+
207+
```bash
208+
./gradlew bootRun
209+
```
210+
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.
212+
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.
214+
215+
216+
## Code Style and Standards
217+
218+
Please adhere to the following coding standards:
219+
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.
223+
224+
Consistent code style helps maintain readability and ease of maintenance.
225+
226+
## Testing
227+
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+
```

‎README.md‎

Lines changed: 7 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -35,6 +35,7 @@ Check out the [Spring User Framework Demo Application](https://github.com/devond
3535
- [Custom User Profiles](#custom-user-profiles)
3636
- [SSO OAuth2 with Google and Facebook](#sso-oauth2-with-google-and-facebook)
3737
- [Examples](#examples)
38+
- [Contributing](#contributing)
3839
- [Reference Documentation](#reference-documentation)
3940
- [License](#license)
4041

@@ -336,6 +337,12 @@ The framework supports SSO OAuth2 with Google, Facebook and Keycloak. To enable
336337

337338
For complete working examples, check out the [Spring User Framework Demo Application](https://github.com/devondragon/SpringUserFrameworkDemoApp).
338339

340+
341+
## Contributing
342+
343+
We welcome contributions of all kinds! If you'd like to help improve SpringUserFramework, please read our [Contributing Guide](CONTRIBUTING.md) for details on how to get started, report issues, and submit pull requests. Let's build something great together!
344+
345+
339346
## Reference Documentation
340347

341348
- [API Documentation](https://digitalSanctuary.github.io/SpringUserFramework/)

0 commit comments

Comments
 (0)