Skip to content

Commit d4cad53

Browse files
Touchie771Touchie771
committed
docs: update README and add CONTRIBUTING guide
- Add comprehensive fees and taxes section to README - Include configuration examples and fee calculation details - Update usage examples to reflect fee system - Add CONTRIBUTING.md with development guidelines - Document coding standards, testing procedures, and PR process
1 parent fe9d5c6 commit d4cad53

File tree

2 files changed

+242
-4
lines changed

2 files changed

+242
-4
lines changed

‎CONTRIBUTING.md‎

Lines changed: 194 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,194 @@
1+
# Contributing to Shopping
2+
3+
Thank you for your interest in contributing to the Shopping plugin! This document provides guidelines and information for contributors.
4+
5+
## Table of Contents
6+
- [Code of Conduct](#code-of-conduct)
7+
- [How to Contribute](#how-to-contribute)
8+
- [Development Setup](#development-setup)
9+
- [Coding Standards](#coding-standards)
10+
- [Testing](#testing)
11+
- [Submitting Changes](#submitting-changes)
12+
- [Reporting Issues](#reporting-issues)
13+
14+
## Code of Conduct
15+
16+
This project follows a simple code of conduct:
17+
- Be respectful and inclusive
18+
- Focus on constructive feedback
19+
- Help create a positive community
20+
21+
## How to Contribute
22+
23+
### Types of Contributions
24+
- **Bug fixes** - Fix existing issues
25+
- **Features** - Add new functionality
26+
- **Documentation** - Improve documentation
27+
- **Testing** - Add or improve tests
28+
29+
### Getting Started
30+
1. Fork the repository
31+
2. Create a feature branch from `main`
32+
3. Make your changes
33+
4. Test thoroughly
34+
5. Submit a pull request
35+
36+
## Development Setup
37+
38+
### Prerequisites
39+
- **Java 21** or higher
40+
- **Gradle 8.5** or higher
41+
- **Minecraft Server** (Paper/Spigot 1.21+) for testing
42+
- **Economy Plugin** (Vault + EssentialsX/CMI)
43+
44+
### Setup Steps
45+
```bash
46+
# Clone your fork
47+
git clone https://github.com/YOUR_USERNAME/Shopping.git
48+
cd Shopping
49+
50+
# Build the project
51+
./gradlew build
52+
53+
# Test in development environment
54+
./gradlew runServer # If you have a test server setup
55+
```
56+
57+
### Project Structure
58+
```
59+
src/main/java/me/touchie771/shopping/
60+
├── Shopping.java # Main plugin class
61+
├── FeesManager.java # Fee and tax system
62+
├── SecurityManager.java # Item restrictions
63+
├── shop/ # Shop system
64+
│ ├── ShopCommand.java
65+
│ ├── ShopHandler.java
66+
│ ├── ShopMenuListener.java
67+
│ └── ShopItem.java
68+
└── auction/ # Auction system
69+
├── AuctionCommand.java
70+
├── AuctionHandler.java
71+
├── AuctionMenuListener.java
72+
├── AuctionTask.java
73+
└── AuctionItem.java
74+
75+
src/main/resources/
76+
├── plugin.yml # Plugin configuration
77+
├── fees.yml # Fee settings
78+
├── security.yml # Item restrictions
79+
└── *.yml # Data files
80+
```
81+
82+
## Coding Standards
83+
84+
### Java Code Style
85+
- Use **UTF-8** encoding
86+
- Follow standard Java naming conventions
87+
- Use meaningful variable and method names
88+
- Add documentation for public methods
89+
- Keep methods focused on single responsibilities
90+
- Use final for immutable variables where appropriate
91+
92+
### Code Quality
93+
- **No emojis** in code or comments
94+
- Write **maintainable code** with clear logic
95+
- Handle exceptions appropriately
96+
- Use logging for debugging (not print statements)
97+
- Keep the codebase clean and well-organized
98+
99+
### Commit Messages
100+
Use clear, descriptive commit messages:
101+
```
102+
feat: add configurable fees system
103+
fix: resolve auction completion bug
104+
docs: update README with fee examples
105+
refactor: improve shop menu performance
106+
```
107+
108+
### Pull Request Guidelines
109+
- **One feature/fix per PR** - Keep changes focused
110+
- **Descriptive title** - Clearly explain what the PR does
111+
- **Detailed description** - Explain the problem and solution
112+
- **Test your changes** - Ensure everything works
113+
- **Update documentation** - If needed
114+
- **Squash commits** - Clean up commit history
115+
116+
## Testing
117+
118+
### Manual Testing
119+
1. **Compile** the plugin: `./gradlew build`
120+
2. **Install** on test server with Vault and economy plugin
121+
3. **Test features**:
122+
- Shop listings and purchases
123+
- Auction creation and bidding
124+
- Fee calculations and tax collection
125+
- Permission checks
126+
- Edge cases (insufficient funds, etc.)
127+
128+
### Test Checklist
129+
- [ ] Shop selling works with fees
130+
- [ ] Shop buying works with taxes
131+
- [ ] Auction starting works with fees
132+
- [ ] Auction completion works with taxes
133+
- [ ] Permissions are respected
134+
- [ ] Error messages are clear
135+
- [ ] Data saves/loads correctly
136+
- [ ] No console errors
137+
138+
## Submitting Changes
139+
140+
### Pull Request Process
141+
1. **Ensure tests pass** and code compiles
142+
2. **Update documentation** if needed
143+
3. **Write clear commit messages**
144+
4. **Create pull request** with detailed description
145+
5. **Respond to feedback** and make requested changes
146+
6. **Wait for review** and approval
147+
148+
### PR Template
149+
```
150+
## Description
151+
Brief description of changes
152+
153+
## Type of Change
154+
- [ ] Bug fix
155+
- [ ] New feature
156+
- [ ] Documentation update
157+
- [ ] Refactoring
158+
159+
## Testing
160+
- [ ] Tested on local server
161+
- [ ] All existing functionality works
162+
- [ ] New features work as expected
163+
164+
## Additional Notes
165+
Any additional context or screenshots
166+
```
167+
168+
## Reporting Issues
169+
170+
### Bug Reports
171+
Please include:
172+
- **Minecraft version** and server type (Paper/Spigot)
173+
- **Plugin version**
174+
- **Steps to reproduce** the issue
175+
- **Expected behavior**
176+
- **Actual behavior**
177+
- **Error logs** if applicable
178+
- **Configuration files** if relevant
179+
180+
### Feature Requests
181+
Please include:
182+
- **Clear description** of the feature
183+
- **Use case** - why is this needed?
184+
- **Implementation ideas** if you have them
185+
- **Mockups** or examples if applicable
186+
187+
## Questions?
188+
189+
If you have questions about contributing:
190+
- Check existing [issues](https://github.com/Touchie771/Shopping/issues) and [discussions](https://github.com/Touchie771/Shopping/discussions)
191+
- Open a [discussion](https://github.com/Touchie771/Shopping/discussions) for questions
192+
- Contact the maintainer
193+
194+
Thank you for contributing to Shopping! 🎉

‎README.md‎

Lines changed: 48 additions & 4 deletions
Original file line numberDiff line numberDiff line change
@@ -10,6 +10,8 @@ A Minecraft plugin that provides a player-driven marketplace with both fixed-pri
1010
- **Automatic Sorting**: Items sorted by price from lowest to highest
1111
- **Item Management**: Remove your listings anytime
1212
- **Economy Integration**: Uses Vault for all transactions
13+
- **Listing Fees**: Configurable fees for creating shop listings
14+
- **Sale Taxes**: Configurable taxes on completed purchases
1315

1416
### Auction System
1517
- **Timed Auctions**: List items with custom duration (1 minute to 24 hours)
@@ -18,6 +20,8 @@ A Minecraft plugin that provides a player-driven marketplace with both fixed-pri
1820
- **Refund System**: Previous bidders are refunded immediately when outbid
1921
- **Offline Support**: Winners receive items even when offline
2022
- **Paginated GUI**: Browse auctions with easy navigation (36 items per page)
23+
- **Listing Fees**: Configurable fees for starting auctions
24+
- **Sale Taxes**: Configurable taxes on completed auctions
2125

2226
## Requirements
2327

@@ -71,22 +75,61 @@ shopping.auction.cancel # Cancel auctions
7175
shopping.auction.claim # Claim items
7276
```
7377

78+
## Fees and Taxes
79+
80+
The plugin includes a comprehensive fee and tax system to generate server revenue and prevent spam listings.
81+
82+
### Configuration
83+
84+
Fees are configured in `plugins/Shopping/fees.yml`:
85+
86+
```yaml
87+
# Enable/disable fees and taxes system
88+
enabled: true
89+
90+
# Listing fees (charged when creating listings)
91+
listing:
92+
enabled: true
93+
flat_fee: 5.0 # Flat fee amount
94+
percentage_fee: 0.05 # 5% of item price
95+
max_percentage_fee: 100.0 # Maximum percentage fee
96+
97+
# Sale taxes (charged on completed sales)
98+
sale_tax:
99+
enabled: true
100+
percentage: 0.10 # 10% tax on sale price
101+
max_tax: 500.0 # Maximum tax amount
102+
103+
# Auction-specific fees
104+
auction:
105+
start_fee: 2.0 # Additional fee for starting auctions
106+
sale_tax_percentage: 0.08 # 8% tax on auction sales
107+
```
108+
109+
### Fee Examples
110+
- **Shop Listing**: $100 item = $5 + $5 (5%) = $10 total fee
111+
- **Shop Purchase**: $100 item + $10 tax = $110 buyer pays, seller gets $90
112+
- **Auction Start**: Listing fee + $2 auction fee
113+
- **Auction Sale**: Seller gets winning bid minus tax
114+
74115
## Usage Examples
75116
76117
### Selling in Shop
77118
```
78119
1. Hold the item you want to sell
79120
2. Run: /shop sell 100
80-
3. Item is listed for $100
81-
4. When someone buys it, you receive the money
121+
3. Pay listing fee ($5 + 5% of item price)
122+
4. Item is listed for $100
123+
5. When someone buys it, you receive the money minus tax
82124
```
83125

84126
### Starting an Auction
85127
```
86128
1. Hold the item you want to auction
87129
2. Run: /auction start 50 30
88-
3. Auction starts at $50 for 30 minutes
89-
4. Highest bidder wins when time expires
130+
3. Pay listing fee + auction start fee ($2)
131+
4. Auction starts at $50 for 30 minutes
132+
5. Highest bidder wins when time expires (minus tax)
90133
```
91134

92135
### Bidding on Auctions
@@ -103,6 +146,7 @@ The plugin stores data in YAML files:
103146
- `plugins/Shopping/items.yml` - Shop listings
104147
- `plugins/Shopping/auctions.yml` - Active auctions
105148
- `plugins/Shopping/pending_items.yml` - Items waiting to be claimed
149+
- `plugins/Shopping/fees.yml` - Fee and tax configuration
106150

107151
## Building from Source
108152

0 commit comments

Comments
 (0)