Thank you for your interest in contributing to PackageURLs.jl! This document provides guidelines and information for contributors.
- Julia 1.6 or later
- Git
-
Clone the repository:
git clone https://github.com/s-celles/PackageURLs.jl.git cd PackageURLs.jl -
Start Julia with the project:
julia --project
-
Install dependencies:
using Pkg Pkg.instantiate()
-
Run tests to verify setup:
Pkg.test()
- Check existing issues to avoid duplicates
- Use the issue templates when available
- Provide a minimal reproducible example
- Include Julia version and OS information
-
Fork the repository and create a feature branch:
git checkout -b feature/your-feature-name
-
Make your changes following our coding standards (see below)
-
Write tests for new functionality (TDD is encouraged)
-
Run the test suite:
using Pkg Pkg.test()
-
Commit your changes using conventional commit format:
feat: add support for new PURL type fix: correct percent-encoding of special characters docs: update API documentation test: add tests for edge cases refactor: simplify parser logic -
Push and create a Pull Request
- Keep PRs focused on a single change
- Update documentation if needed
- Ensure all tests pass
- Add tests for new functionality
- Follow the existing code style
- Follow the Julia Style Guide
- Use 4 spaces for indentation (no tabs)
- Maximum line length of 92 characters
- Use descriptive variable and function names
- Add docstrings to all exported functions and types
- Use Julia's docstring format with examples:
"""
""" function_name(arg1, arg2) -> ReturnType Brief description of what the function does. # Arguments - `arg1`: Description of first argument - `arg2`: Description of second argument # Examples ```julia result = function_name(x, y)
- Write tests before implementation (TDD)
- Place tests in
test/directory - Use descriptive test names
- Test both success and error cases
- Aim for high code coverage
Example test structure:
@testset "Feature Name" begin
@testset "success cases" begin
@test expected_behavior()
end
@testset "error cases" begin
@test_throws ErrorType invalid_input()
end
endPackageURLs.jl/
├── src/
│ ├── PackageURLs.jl # Main module
│ ├── types.jl # Core types (PURL, PURLError)
│ ├── parse.jl # Parsing implementation
│ ├── serialize.jl # String conversion
│ ├── encoding.jl # Percent encoding/decoding
│ ├── qualifiers.jl # Qualifier handling
│ ├── validation.jl # Type-specific validation
│ └── macro.jl # String macro
├── test/
│ ├── runtests.jl # Test entry point
│ ├── test_*.jl # Test files
│ └── fixtures/ # Test fixtures
├── docs/
│ ├── src/ # Documentation source
│ └── make.jl # Documenter.jl config
└── Project.toml # Package metadata
PackageURLs.jl uses official type definitions from the purl-spec repository. These definitions follow the ECMA-427 schema.
-
Run the download script to fetch the latest definitions:
julia --project scripts/download_type_definitions.jl
-
Run tests to verify all definitions load correctly:
julia --project -e 'using Pkg; Pkg.test()' -
Check for schema validation issues (see
UPSTREAM-ISSUES.mdfor known issues)
When new types are added to purl-spec:
-
Add the type name to
OFFICIAL_TYPESinscripts/download_type_definitions.jl -
Run the download script:
julia --project scripts/download_type_definitions.jl
-
Verify the type loads correctly:
using PackageURLs def = load_type_definition("data/type_definitions/newtype.json")
-
Add specific normalization tests if the type has special rules
-
Update
test/test_type_definitions.jlto include the new type
Type definitions are validated against the official schema:
https://packageurl.org/schemas/purl-type-definition.schema-1.0.json
Key fields extracted by load_type_definition():
type: The PURL type identifierdescription: Human-readable descriptionname_definition.case_sensitive: Determines if names need lowercase normalizationname_definition.normalization_rules: Additional normalization (e.g., underscore replacement)qualifiers_definition: List of known/required qualifiers
The purl-spec repository is the source of truth for PURL type definitions.
- Fork the purl-spec repository
- Add the type definition in
types/following the schema - Include:
- Type name and description
- Namespace, name, version definitions
- Qualifier definitions if applicable
- Example PURLs
- Submit a pull request with rationale
The Julia PURL type was added via purl-spec#540.
Example Julia PURLs:
pkg:julia/Dates@1.9.0?uuid=ade2ca70-3891-5945-98fb-dc099432e06a
pkg:julia/PackageURLs@0.4.0?uuid=c2271b70-7219-4bda-bcc3-62ec08ead5b7
To add type-specific validation for a new package ecosystem:
-
Add a new
TypeRulessubtype insrc/validation.jl:struct NewTypeRules <: TypeRules end
-
Update
type_rules()dispatch:function type_rules(purl_type::AbstractString) t == "newtype" && return NewTypeRules() # ... end
-
Implement normalization and validation:
normalize_name(::NewTypeRules, name) = # normalization logic validate_purl(::NewTypeRules, purl) = # validation logic
-
Add tests in
test/test_validation.jl -
Update documentation
using Pkg
Pkg.test(coverage=true)Tests automatically include Aqua.jl checks for:
- Ambiguities
- Unbound type parameters
- Undefined exports
- Project dependencies
julia --project=docs -e 'using Pkg; Pkg.instantiate(); include("docs/make.jl")'- Open an issue for questions
- Check existing documentation
- Review the PURL specification
By contributing to PackageURLs.jl, you agree that your contributions will be licensed under the MIT License.