Skip to content

Commit 3e88920

Browse files
fmontesfmontes
committed
Add CONTRIBUTING.md with development guidelines
- Bug reporting and enhancement request guidelines - Development setup and workflow - Code style and OSGi considerations - Testing checklist - Pull request process - Semantic versioning explanation
1 parent 16d24c7 commit 3e88920

1 file changed

Lines changed: 209 additions & 0 deletions

File tree

‎CONTRIBUTING.md‎

Lines changed: 209 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,209 @@
1+
# Contributing to Google Analytics Plugin for dotCMS
2+
3+
Thank you for your interest in contributing to the Google Analytics plugin! This document provides guidelines and instructions for contributing.
4+
5+
## Code of Conduct
6+
7+
By participating in this project, you agree to abide by the dotCMS [Code of Conduct](https://dotcms.com/code-of-conduct). Please be respectful and constructive in all interactions.
8+
9+
## How Can I Contribute?
10+
11+
### Reporting Bugs
12+
13+
Before creating a bug report:
14+
- Check the [existing issues](https://github.com/dotCMS/google-analytics/issues) to avoid duplicates
15+
- Verify you're using the latest version of the plugin
16+
- Test with a clean dotCMS installation if possible
17+
18+
When creating a bug report, include:
19+
- **Plugin version** (e.g., 0.4.1)
20+
- **dotCMS version** (e.g., 23.01.10)
21+
- **Steps to reproduce** the issue
22+
- **Expected behavior** vs. **actual behavior**
23+
- **Error messages** from dotCMS logs
24+
- **Sample Velocity code** that demonstrates the issue
25+
26+
### Suggesting Enhancements
27+
28+
Enhancement suggestions are welcome! Please include:
29+
- **Clear use case** - What problem does this solve?
30+
- **Proposed solution** - How should it work?
31+
- **Alternatives considered** - What other approaches did you think about?
32+
- **Impact** - Who benefits from this enhancement?
33+
34+
### Pull Requests
35+
36+
We actively welcome pull requests!
37+
38+
#### Before You Start
39+
40+
1. **Check existing issues/PRs** - Someone might already be working on it
41+
2. **Open an issue first** for significant changes to discuss the approach
42+
3. **Keep changes focused** - One feature/fix per PR
43+
44+
#### Development Setup
45+
46+
1. **Fork and clone the repository**
47+
```bash
48+
git fork https://github.com/dotCMS/google-analytics.git
49+
cd google-analytics
50+
```
51+
52+
2. **Create a feature branch**
53+
```bash
54+
git checkout -b feature/your-feature-name
55+
# or
56+
git checkout -b fix/issue-description
57+
```
58+
59+
3. **Set up your development environment**
60+
- JDK 11 or higher
61+
- Gradle (included via wrapper)
62+
- A running dotCMS instance for testing (local or Docker)
63+
64+
4. **Build the plugin**
65+
```bash
66+
./gradlew clean jar
67+
```
68+
69+
The JAR will be in `build/libs/google-analytics-X.X.X.jar`
70+
71+
#### Making Changes
72+
73+
1. **Write clean, readable code**
74+
- Follow existing code style and patterns
75+
- Add comments for complex logic
76+
- Keep methods focused and concise
77+
78+
2. **Test your changes**
79+
- Build the plugin: `./gradlew jar`
80+
- Upload to a dotCMS instance
81+
- Test with real Google Analytics data
82+
- Verify OSGi bundle loads without errors
83+
- Test Velocity viewtool functionality
84+
85+
3. **Update documentation**
86+
- Update README.md if you changed functionality
87+
- Add/update code comments
88+
- Document new viewtool methods or parameters
89+
90+
4. **Commit your changes**
91+
```bash
92+
git add .
93+
git commit -m "Brief description of changes
94+
95+
Longer explanation of what changed and why.
96+
Include any breaking changes or migration notes."
97+
```
98+
99+
**Commit message guidelines:**
100+
- Use present tense ("Add feature" not "Added feature")
101+
- Be concise but descriptive
102+
- Reference issues when applicable (`Fixes #123`)
103+
104+
#### Submitting Your PR
105+
106+
1. **Push to your fork**
107+
```bash
108+
git push origin feature/your-feature-name
109+
```
110+
111+
2. **Create a Pull Request**
112+
- Go to the [repository](https://github.com/dotCMS/google-analytics)
113+
- Click "New Pull Request"
114+
- Select your fork and branch
115+
- Fill out the PR template with:
116+
- **What changed** - Clear description of changes
117+
- **Why** - The problem this solves
118+
- **Testing** - How you tested the changes
119+
- **Breaking changes** - Any compatibility issues
120+
- **Related issues** - Link to related issues
121+
122+
3. **Address review feedback**
123+
- Be responsive to comments
124+
- Make requested changes in new commits
125+
- Ask questions if feedback is unclear
126+
127+
## Development Guidelines
128+
129+
### Code Style
130+
131+
- **Java**: Follow standard Java conventions
132+
- **Indentation**: 4 spaces (no tabs)
133+
- **Braces**: Opening brace on same line
134+
- **Naming**:
135+
- Classes: `PascalCase`
136+
- Methods/variables: `camelCase`
137+
- Constants: `UPPER_SNAKE_CASE`
138+
139+
### OSGi Considerations
140+
141+
When adding dependencies:
142+
143+
1. **Check if dotCMS already provides it** - Use `compileOnly` if yes
144+
2. **Bundle third-party libraries** - Add to `osgiLibs` configuration
145+
3. **Update Import-Package** - Exclude bundled packages from imports
146+
4. **Test OSGi wiring** - Verify bundle loads in clean dotCMS instance
147+
148+
Example from `build.gradle`:
149+
```gradle
150+
dependencies {
151+
compileOnly('com.dotcms:dotcms:23.01.10') { transitive = true }
152+
implementation (group: 'your.library', name: 'artifact', version: '1.0.0')
153+
osgiLibs (group: 'your.library', name: 'artifact', version: '1.0.0')
154+
}
155+
156+
'Import-Package': '''
157+
!your.library.*,
158+
javax.*,
159+
com.dotcms.*,
160+
...
161+
'''
162+
```
163+
164+
### Testing Checklist
165+
166+
Before submitting a PR, verify:
167+
168+
- [ ] Plugin builds without errors: `./gradlew clean jar`
169+
- [ ] JAR uploads successfully to dotCMS
170+
- [ ] OSGi bundle starts without errors (check logs for "Starting Google Analytics OSGI plugin")
171+
- [ ] Viewtool is available in Velocity (`$analytics`)
172+
- [ ] Can create analytics request and query GA4 data
173+
- [ ] No breaking changes to existing Velocity code (or documented if necessary)
174+
- [ ] Works with dotCMS 23.01.10 and newer
175+
176+
## Versioning
177+
178+
This plugin follows [Semantic Versioning](https://semver.org/):
179+
180+
- **Major (X.0.0)**: Breaking changes
181+
- **Minor (0.X.0)**: New features, backward compatible
182+
- **Patch (0.0.X)**: Bug fixes, backward compatible
183+
184+
Version is managed in `build.gradle`. Don't change it in your PR unless coordinating with maintainers.
185+
186+
## Release Process
187+
188+
Releases are automated via GitHub Actions:
189+
190+
1. PR is merged to `main`
191+
2. GitHub Actions builds the plugin
192+
3. Creates a GitHub release with the JAR attached
193+
4. Tags the release with version from `build.gradle`
194+
195+
Only maintainers can merge to `main` and trigger releases.
196+
197+
## Questions?
198+
199+
- **General questions**: [dotCMS Community Forums](https://dotcms.com/forums)
200+
- **Plugin-specific**: [Open an issue](https://github.com/dotCMS/google-analytics/issues)
201+
- **dotCMS development**: [dotCMS Developer Docs](https://dotcms.com/docs)
202+
203+
## License
204+
205+
By contributing, you agree that your contributions will be licensed under the same terms as the project.
206+
207+
---
208+
209+
Thank you for contributing to make dotCMS better! 🎉

0 commit comments

Comments
 (0)