Edit chat shape

CONTRIBUTING.md

@@ -1,217 +1,123 @@
 # Contributing to the Solid SHACL Shapes Catalogue
 
-Thank you for your interest in contributing. 
-
 This repository accepts contributions of SHACL shapes, improvements to existing shapes, and documentation updates. All contributions are reviewed through a GitHub pull request (PR) process. 
 
 If you have feedback on this process, please raise it in the **[GitHub discussion](https://github.com/solid/shapes/discussions/20)**.
 
 
-## Guidelines for Contributing
+## Guidelines
 
-When contributing, you MUST:
+When contributing:
 
+- Create a new branch
 - Check whether a domain file already exists
 - Follow the naming conventions defined in this document
 - Include documentation using the GitHub PR template
 - Ensure shapes validate before submitting
 
-### Branching Requirements
-
-All contributions MUST be made from a separate branch.
-
-- Do NOT commit directly to the `main` branch
-- Create a new branch for each contribution or feature
-- Use a clear and descriptive branch name
-
-## Adding Shapes
-
-### Existing Domains
 
-Each domain MUST have a single `{domain}.ttl` file.
 
-- If a domain file exists, add your shape to that file where appropriate
-- Do NOT create duplicate domain files
-
-### New Domains
-
-If a domain file does not exist, create a new file:
-
-```
-/shapes/{domain}.ttl
-```
-
-### Rules
+## Pull Request Process
 
-- Domain names MUST be lowercase
-- Domain names SHOULD be a minimal representation of the semantic concept
+* Create branch 
+* Ensure the shape validates before opening a PR
+    * [validation scripts](./scripts) are available 
+* Open a PR and complete the questions in the PR template provided
+* Respond to review feedback and iterate as needed
 
-If using vocabularies, follow community ontology naming conventions.  
-If unsure, check: https://prefix.cc
+All contributions are subject to peer review before merging.
 
+## Branch Requirements
 
+All contributions must be made from a separate branch. 
 
-## Naming Conventions
+## Domain Files
 
-### Namespace Structure
+Each domain has a {domain}.ttl file. If a domain file exists, add your shape to that file otherwise create a new file in the shapes directory /shapes/{domain}.ttl. Domain file names are lowercase and should be a minimal representation of the semantic concept.
 
-Use the following pattern:
+### Namespace and Prefix Conventions
 
+Use the following pattern for namespace:
 ```
-[https://solidproject.org/shapes/{domain}#](https://solidproject.org/shapes/{domain}#)
-```
-
-Examples:
+https://solidproject.org/shapes/{domain}#
 ```
-[https://solidproject.org/shapes/address#](https://solidproject.org/shapes/address#)
-[https://solidproject.org/shapes/vcard#](https://solidproject.org/shapes/vcard#)
-````
-
 
-
-### Prefix Naming
-
-- Prefix labels MUST begin with a letter
-- Prefix labels MAY use lowercase letters, hyphens, or underscores
-
-Example:
+Prefix labels must begin with a letter and use lowercase letters, hyphens, or underscores, e.g.:
 
 ```turtle
 @prefix address-shape: <https://solidproject.org/shapes/address#> .
-@prefix vcard-shape: <https://solidproject.org/shapes/vcard#> .
-@prefix sh: <http://www.w3.org/ns/shacl#> .
-````
-
+```
 
 
-### Shape Naming
+### Multiple Shapes per Domain
 
-* Shape names MUST use PascalCase
-* Shape names MUST end with `Shape`
+A goal of the solid/shapes repository is to work towards consensus on a single shape for a given domain where possible. Where this is not possible, multiple shapes may exist for a given domain. If a new shape needs to be added for an existing domain, naming conventions recommend the use of a semantic variation for the shape name, e.g.:
 
-Examples:
 ```
 address-shape:AddressShape
-vcard-shape:VCardAddressShape
+address-shape:AddressMinimalShape
 ```
 
+## Shape Name
 
-## Multiple Shapes per Domain
 
-Multiple shapes MAY exist within a single domain.
 
-* Use semantic variation rather than creating new namespaces
+Shape names should use PascalCase abd end with `Shape`, e.g.:
 
-Example:
 ```
 address-shape:AddressShape
-address-shape:AddressMinimalShape
 ```
 
 
-## Validation Rules
 
-Shapes SHOULD follow these guidelines:
 
-* Prefer optional validation to maximise Pod interoperability
-* Keep constraints focused on structural validation
+## Validation Rules
+A goal of solid/shapes is to support interoperability in the Solid ecosystem, and with this in mind, it is recommended that shapes should have constraints that maximise their potential reuse. 
 
-## Shape Immutability Policy
 
-Shapes published to this catalogue are **immutable**.
+## Shape Immutability Policy
 
-Once a shape is merged and published:
+Shapes published to this catalogue are **immutable** to ensure predictable behaviour for applications/agents that might use them. Once a shape is merged and published:
 
 * Shapes MUST NOT be modified in place
 * Validation rules MUST NOT be changed retrospectively
 * Structural or semantic changes MUST be introduced via new shapes
 
-This ensures predictable behaviour for applications using Solid Pods.
-
-
-
-### Why Shapes Are Immutable
-
-Shapes function as contracts between applications and user data. Modifying a published shape can cause:
-
-* Validation inconsistencies across applications
-* Silent breaking changes in decentralized clients
-* Data interoperability failures
-
-Immutability ensures that applications can safely cache and reuse shapes.
-
-
 
 ## Evolving Shapes
 
-If validation rules need to change, you MUST create a new shape.
-
-### Recommended Approach
-
-#### Create a New Shape Variant
-
-Example:
-
-```
-address-shape:AddressShape
-address-shape:AddressStrictShape
-```
-
-
-
-### When Adding New Constraints
-
-You MUST NOT:
-
-* Add new mandatory fields to existing shapes
-* Change cardinality rules of existing properties
-* Change target class mappings
-
-Instead:
-
-* Introduce a new shape variant or version
+The Solid/shapes repository supports the evolution of shapes, where a change to the shape is not a breaking change.
 
-You MAY:
+A non-breaking change for a domain file would be:
+* Addition of a new optional property
+* Addition of metadata/documentation
+* Addition of a new shapes
 
-* Add new optional properties
-* Add documentation
-* Add new shapes
+A breaking change for an existing shape would be:
+* Addition of a new mandatory field 
+* Change of cardinality rules of existing properties
+* Change of target class mappings
 
-
-
-
-
-## Pull Request Process
-
-* Submit a PR with a clear description of the shape and its purpose
-* Indicate whether you are modifying an existing domain or creating a new one
-* Ensure the shape validates before submission
-* Include documentation using the PR template
-* Respond to review feedback and iterate as needed
-
-All contributions are subject to peer review before merging.
+If validation rules need to change for a published shape that would constitute a breaking change, a new shape should be created.
 
 ## Contributor Checklist
 
 Before submitting your PR, ensure:
 
-* [ ] The shape validates successfully
-* [ ] Naming conventions are followed
 * [ ] The correct domain file is used or created
-* [ ] Documentation is included
 * [ ] No existing shapes are modified in a breaking way
+* [ ] Naming conventions are followed
+* [ ] The shape validates successfully
+* [ ] Descriptive metadata is included
 
 
 ## Human Consensus Process
 
-In addition to the contribution process described above, there is an important **human consensus** step that we are still refining. For example:
+In addition to the contribution process described above, there is an important **human consensus** step that we are still refining. 
 
-```
 If a PR introduces a shape that overlaps conceptually with an existing one, we will ask contributors to collaborate with the current maintainer(s) of that shape, aiming to align on a shared model where possible.
 
 If alignment is reached, contributors should work together to evolve the existing shape. If not, both shapes can continue to be maintained independently.
-```
-
 
 If you have feedback on this process, please raise it in the **[GitHub discussion](https://github.com/solid/shapes/discussions/20)**.