Skip to content

Commit fa9f675

Browse files
andrewandrew
committed
Update docs
1 parent c54624e commit fa9f675

File tree

4 files changed

+337
-4
lines changed

4 files changed

+337
-4
lines changed

‎CONTRIBUTING.md‎

Lines changed: 167 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,167 @@
1+
# Contributing to Purl
2+
3+
Thank you for your interest in contributing to the Purl Ruby library! This document provides guidelines and information for contributors.
4+
5+
## Code of Conduct
6+
7+
This project and everyone participating in it is governed by our [Code of Conduct](CODE_OF_CONDUCT.md). By participating, you are expected to uphold this code.
8+
9+
## How to Contribute
10+
11+
### Reporting Issues
12+
13+
Before creating an issue, please:
14+
1. Search existing issues to avoid duplicates
15+
2. Use the latest version of the gem
16+
3. Provide a clear, descriptive title
17+
4. Include steps to reproduce the issue
18+
5. Share relevant code examples or error messages
19+
20+
### Suggesting Enhancements
21+
22+
Enhancement suggestions are welcome! Please:
23+
1. Check if the enhancement is already requested
24+
2. Explain the use case and expected behavior
25+
3. Consider if it fits the project's scope
26+
4. Be willing to help implement if accepted
27+
28+
### Pull Requests
29+
30+
1. **Fork** the repository
31+
2. **Create** a feature branch (`git checkout -b my-new-feature`)
32+
3. **Make** your changes following our coding standards
33+
4. **Add** tests for your changes
34+
5. **Ensure** all tests pass (`rake test`)
35+
6. **Run** the full test suite including compliance tests
36+
7. **Commit** your changes with clear, descriptive messages
37+
8. **Push** to your branch (`git push origin my-new-feature`)
38+
9. **Create** a Pull Request with a clear description
39+
40+
## Development Setup
41+
42+
### Prerequisites
43+
44+
- Ruby 3.1 or higher
45+
- Bundler gem
46+
47+
### Setup
48+
49+
```bash
50+
git clone https://github.com/package-url/purl-ruby.git
51+
cd purl-ruby
52+
bundle install
53+
```
54+
55+
### Running Tests
56+
57+
```bash
58+
# Run all tests
59+
rake test
60+
61+
# Run PURL specification compliance tests
62+
rake spec:compliance
63+
64+
# Validate JSON schemas
65+
rake spec:validate_schemas
66+
67+
# Validate PURL examples
68+
rake spec:validate_examples
69+
70+
# Show all available tasks
71+
rake -T
72+
```
73+
74+
### Coding Standards
75+
76+
- Follow Ruby best practices and conventions
77+
- Use meaningful variable and method names
78+
- Add documentation for public methods
79+
- Keep methods focused and concise
80+
- Follow the existing code style
81+
82+
### Testing Requirements
83+
84+
All contributions must include appropriate tests:
85+
86+
- **Unit tests** for new functionality
87+
- **Integration tests** for feature interactions
88+
- **Compliance tests** must continue to pass
89+
- **Example validation** for any new PURL examples
90+
91+
### Documentation
92+
93+
- Update the README.md if adding new features
94+
- Add inline documentation for complex methods
95+
- Update CHANGELOG.md following the format
96+
- Include examples in documentation
97+
98+
## Project Structure
99+
100+
```
101+
├── lib/
102+
│ ├── purl.rb # Main module
103+
│ └── purl/
104+
│ ├── errors.rb # Error classes
105+
│ ├── package_url.rb # Core PURL parsing
106+
│ └── registry_url.rb # Registry URL handling
107+
├── test/ # Test files
108+
├── schemas/ # JSON schemas
109+
├── purl-types.json # Package types configuration
110+
└── test-suite-data.json # Official test cases
111+
```
112+
113+
## Adding New Package Types
114+
115+
To add support for a new package type:
116+
117+
1. **Add type definition** to `purl-types.json`
118+
2. **Include examples** from the official specification
119+
3. **Add registry configuration** if applicable
120+
4. **Update tests** to verify the new type
121+
5. **Run validation** to ensure compliance
122+
123+
## JSON Schema Updates
124+
125+
When modifying JSON files:
126+
127+
1. **Validate** against schemas: `rake spec:validate_schemas`
128+
2. **Update schemas** if structure changes
129+
3. **Test examples** are valid: `rake spec:validate_examples`
130+
131+
## PURL Specification Compliance
132+
133+
This library maintains 100% compliance with the official PURL specification:
134+
135+
- All changes must maintain compliance
136+
- Run `rake spec:compliance` before submitting
137+
- New features should align with the spec
138+
- Report spec issues upstream when discovered
139+
140+
## Release Process
141+
142+
Releases are handled by maintainers:
143+
144+
1. Update version in `lib/purl/version.rb`
145+
2. Update `CHANGELOG.md` with changes
146+
3. Run full test suite
147+
4. Create release tag
148+
5. Publish to RubyGems
149+
150+
## Getting Help
151+
152+
- **Issues**: Use GitHub issues for bugs and feature requests
153+
- **Discussions**: Use GitHub discussions for questions
154+
- **Security**: Follow our [Security Policy](SECURITY.md)
155+
156+
## Recognition
157+
158+
Contributors will be recognized in:
159+
- Git commit history
160+
- CHANGELOG.md for significant contributions
161+
- Project documentation where appropriate
162+
163+
## License
164+
165+
By contributing to Purl, you agree that your contributions will be licensed under the [MIT License](LICENSE).
166+
167+
Thank you for contributing to make Purl better for everyone!

‎README.md‎

Lines changed: 3 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -1,10 +1,10 @@
11
# Purl - Package URL Parser for Ruby
22

3-
A comprehensive Ruby library for parsing, validating, and working with Package URLs (PURLs) as defined by the [PURL specification](https://github.com/package-url/purl-spec).
3+
A Ruby library for parsing, validating, and generating Package URLs (PURLs) as defined by the [PURL specification](https://github.com/package-url/purl-spec).
44

5-
This library provides better error handling than existing solutions with namespaced error types, bidirectional registry URL conversion, and JSON-based configuration for cross-language compatibility.
5+
This library features comprehensive error handling with namespaced error types, bidirectional registry URL conversion, and JSON-based configuration for cross-language compatibility.
66

7-
[![Ruby](https://img.shields.io/badge/ruby-%3E%3D%202.7-red.svg)](https://www.ruby-lang.org/)
7+
[![Ruby](https://img.shields.io/badge/ruby-%3E%3D%203.1-red.svg)](https://www.ruby-lang.org/)
88
[![Gem Version](https://badge.fury.io/rb/purl.svg)](https://rubygems.org/gems/purl)
99
[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
1010

‎SECURITY.md‎

Lines changed: 164 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,164 @@
1+
# Security Policy
2+
3+
## Supported Versions
4+
5+
We actively support and provide security updates for the following versions:
6+
7+
| Version | Supported |
8+
| ------- | ------------------ |
9+
| 1.x.x | :white_check_mark: |
10+
| < 1.0 | :x: |
11+
12+
## Reporting a Vulnerability
13+
14+
The Purl team takes security seriously. If you discover a security vulnerability, please follow these steps:
15+
16+
### 1. Do NOT Create a Public Issue
17+
18+
Please do not report security vulnerabilities through public GitHub issues, discussions, or pull requests.
19+
20+
### 2. Report Privately
21+
22+
Send a detailed report to **[email protected]** with:
23+
24+
- **Subject**: `[SECURITY] Purl Ruby - [Brief Description]`
25+
- **Description** of the vulnerability
26+
- **Steps to reproduce** the issue
27+
- **Potential impact** assessment
28+
- **Suggested fix** (if you have one)
29+
- **Your contact information** for follow-up
30+
31+
### 3. What to Include
32+
33+
Please provide as much information as possible:
34+
35+
```
36+
- Affected versions
37+
- Attack vectors
38+
- Proof of concept (if safe to share)
39+
- Environmental details (Ruby version, OS, etc.)
40+
- Any relevant configuration details
41+
```
42+
43+
## Response Process
44+
45+
### Initial Response
46+
47+
- **24-48 hours**: We will acknowledge receipt of your report
48+
- **Initial assessment**: Within 1 week of acknowledgment
49+
- **Status updates**: Weekly until resolution
50+
51+
### Investigation
52+
53+
We will:
54+
1. **Confirm** the vulnerability exists
55+
2. **Assess** the severity and impact
56+
3. **Develop** a fix and mitigation strategy
57+
4. **Test** the fix thoroughly
58+
5. **Coordinate** disclosure timeline
59+
60+
### Resolution
61+
62+
- **High/Critical**: Immediate fix and release
63+
- **Medium**: Fix within 30 days
64+
- **Low**: Fix in next regular release cycle
65+
66+
## Security Considerations
67+
68+
### Input Validation
69+
70+
The Purl library processes Package URL strings and performs:
71+
72+
- **Scheme validation**: Ensures proper `pkg:` prefix
73+
- **Component parsing**: Validates type, namespace, name, version
74+
- **URI encoding**: Handles percent-encoded characters
75+
- **Qualifier parsing**: Processes key-value parameters
76+
77+
### Potential Risk Areas
78+
79+
Areas that warrant security attention:
80+
81+
1. **URL Parsing**: Malformed URLs could cause parsing errors
82+
2. **Regular Expressions**: Complex patterns may be vulnerable to ReDoS
83+
3. **JSON Processing**: Configuration files require safe parsing
84+
4. **Network Requests**: Registry URL generation involves external URLs
85+
86+
### Safe Usage Practices
87+
88+
When using Purl in applications:
89+
90+
- **Validate input**: Don't trust user-provided PURL strings
91+
- **Handle errors**: Properly catch and handle parsing exceptions
92+
- **Sanitize output**: Be careful when displaying parsed components
93+
- **Rate limiting**: If parsing many PURLs, implement appropriate limits
94+
95+
## Disclosure Policy
96+
97+
### Coordinated Disclosure
98+
99+
We follow coordinated disclosure principles:
100+
101+
1. **Private reporting** allows us to fix issues before public disclosure
102+
2. **Reasonable timeline** for fixes (typically 90 days maximum)
103+
3. **Credit and recognition** for responsible reporters
104+
4. **Public disclosure** after fixes are available
105+
106+
### Public Disclosure
107+
108+
After a fix is released:
109+
110+
1. **Security advisory** published on GitHub
111+
2. **CVE requested** if applicable
112+
3. **Release notes** include security information
113+
4. **Community notification** through appropriate channels
114+
115+
## Security Updates
116+
117+
### Notification Channels
118+
119+
Security updates are announced through:
120+
121+
- **GitHub Security Advisories**
122+
- **RubyGems security alerts**
123+
- **Release notes and CHANGELOG**
124+
- **Project README updates**
125+
126+
### Update Recommendations
127+
128+
To stay secure:
129+
130+
- **Monitor** our security advisories
131+
- **Update regularly** to the latest version
132+
- **Review** release notes for security fixes
133+
- **Subscribe** to GitHub notifications for this repository
134+
135+
## Bug Bounty
136+
137+
Currently, we do not offer a formal bug bounty program. However, we deeply appreciate security researchers who help improve the project's security posture.
138+
139+
### Recognition
140+
141+
Contributors who responsibly disclose security issues will be:
142+
143+
- **Credited** in security advisories (with permission)
144+
- **Mentioned** in release notes
145+
- **Recognized** in project documentation
146+
- **Thanked** publicly (unless anonymity is requested)
147+
148+
## Contact Information
149+
150+
**Security Contact**: [email protected]
151+
152+
**PGP Key**: Available upon request for encrypted communications
153+
154+
**Response Time**: We aim to acknowledge security reports within 24-48 hours
155+
156+
## Additional Resources
157+
158+
- [PURL Specification Security Considerations](https://github.com/package-url/purl-spec)
159+
- [Ruby Security Best Practices](https://guides.rubyonrails.org/security.html)
160+
- [OWASP Secure Coding Practices](https://owasp.org/www-project-secure-coding-practices-quick-reference-guide/)
161+
162+
---
163+
164+
Thank you for helping keep Purl and its users safe!

‎purl.gemspec‎

Lines changed: 3 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -9,8 +9,10 @@ Gem::Specification.new do |spec|
99
spec.email = ["[email protected]"]
1010

1111
spec.summary = "Parse and convert package urls (purls)"
12+
spec.description = "This library features comprehensive error handling with namespaced error types, bidirectional registry URL conversion, and JSON-based configuration for cross-language compatibility.
13+
It supports 37 package types (32 official + 5 additional ecosystems) and is fully compliant with the official PURL specification test suite."
1214
spec.homepage = "https://github.com/andrew/purl"
13-
spec.required_ruby_version = ">= 3.2.0"
15+
spec.required_ruby_version = ">= 3.1.0"
1416

1517
spec.metadata["allowed_push_host"] = "https://rubygems.org"
1618
spec.metadata["homepage_uri"] = spec.homepage

0 commit comments

Comments
 (0)