Skip to content

Commit

Permalink
add separate contributing guide
Browse files Browse the repository at this point in the history
  • Loading branch information
@coolharsh55
coolharsh55 committed Dec 4, 2022
1 parent 1b4fba2 commit d5fc242
Show file tree
Hide file tree
Showing 2 changed files with 48 additions and 41 deletions.
43 changes: 2 additions & 41 deletions README.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -9,6 +9,8 @@ The mission of the W3C Data Privacy Vocabularies and Controls CG (DPVCG) is to d
License: All work produced by DPVCG and provided through this repo or elsewhere is provided by contributors under the [W3C Document License](https://www.w3.org/Consortium/Legal/2015/doc-license). A copy of the license is provided in the [LICENSE.md](./LICENSE.md) file.

Contributing: See [contributing.md](./contributing.md)

## Releases

> [latest release](https://github.com/w3c/dpv/releases/latest)
Expand Down Expand Up @@ -75,47 +77,6 @@ The namespace for DPV terms is `http://www.w3id.org/dpv#` with suggested prefix

The term 'DPV' represents the entire vocabulary - with its concepts and terms as defined in the specification. Serialisations for this in `rdf+xml`, `json-ld`, and `turtle` are provided. The 'modules' in DPV are separate files for each of the hierarchies and concept taxonomies - for example 'purposes'. These are defined in the `rdf` folder with serialisations for each module. The `core` or `base` vocabulary or ontology is defined containing the top-level classes and data model (i.e. `PersonalDataHandling`).

## Contribution / Participation

The DPVCG is the primary forum for contributions and participations regarding the DPV. As such, all decisions and resolutions will be conducted through the group's meetings and call. Membership in DPVCG is not necessary to contribute to DPV, but is recommended for participating in the group's decision making process. Contributions and questions can be sent to the group's [public mailing list](https://lists.w3.org/Archives/Public/public-dpvcg/) or expressed as [GitHub issues](https://github.com/dpvcg/dpv/issues).

## Suggesting new terms

To suggest a new term, we request following information:

> Please ensure the terms follow the [style guides](./documentation-generator/style-guide.md)
* _term_
* _description of the term_
* whether it should be a _class_ or _a property_
* relation to existing term(s) in DPV e.g. through sub-classes
* source (where applicable)
* justification or relevance of why this term should be added (where not obvious)

Suggestions are welcome via the group's meetings, mailing list, and GitHub issues.

## Raising issues

Before submitting an issue, please see the whether the issue has been addressed on [GitHub](https://github.com/w3c/dpv/issues). If not, please raise the issue via the group's [public mailing list](https://lists.w3.org/Archives/Public/public-dpvcg/) or expressed as [GitHub issues](https://github.com/w3c/dpv/issues).

Fixes, corrections to the terms are considered as issues and can be submitted similarly. For minor changes, we may prefer to incorporate them directly rather than through pull requests and patches. For larger issues, please check with the group before submitting a pull-request to ensure its appropriate and efficient incorporation.

## Development Guide

> (1) DO NOT change the outputs (HTML, RDF) directly - they are autogenerated from a different set of inputs
>
> (2) DO NOT make changes over the `main` branch - use the `dev` branch to make changes or raise PRs
The development and maintainence of DPV takes place primarily through shared spreadsheets (see [documentation-generator/vocab_csv](./documentation-generator/vocab_csv) folder). The terms and their annotated metadata are declared in the spreadsheet, and used as input to generate the RDF files and HTML documentation through the [documentation-generator](https://github.com/w3c/dpv/tree/master/documentation-generator) tooling. The `documentation` tool is a collection of Python scripts to assist in the automation of downloading the spreadsheet as CSV files, generating RDF files, validating them for correctness, and producing the HTML documentation.

Therefore, whenever adding a new term or changing existing ones, the following steps are recommended to update the DPV vocabulary and documentation:

1. Make changes appropriately in the shared spreadsheet. The links to this are available to the DPVCG members. For others, please see the CSV files in `documentation_generator/vocab_csv`. Ideally, create an GitHub issue for discussions and follow ups.
2. Use the [documentation-generator](./documentation-generator/) tooling to download the spreadsheet, generate RDF, test it, generate HTML output.
3. Manually inspect whether the changes have been made. Tools, scripts, and software in general can propogate errors silently.
4. The variables and parameters in [documentation-generator](https://github.com/w3c/dpv/tree/master/documentation-generator) tooling can be used to define the path where files are exported to can be set to the `dpv` repository to make changes in this directory. For e.g. `EXPORT_DPV_HTML_PATH = ~/code/dpvcg/dpv` will generate the HTML documentation in the `dpv` directory.
5. Submit a pull-request for merging with the repository.

## Getting help and assistance

If you're unsure about something, or would like clarifications, or suggestions - please communicate with us or open an issue. We would be happy to help.
46 changes: 46 additions & 0 deletions contributing.md
View file
Original file line number Diff line number Diff line change
@@ -0,0 +1,46 @@
# DPV Contribution Guide

## Contribution / Participation

The DPVCG is the primary forum for contributions and participations regarding the DPV. As such, all decisions and resolutions will be conducted through the group's meetings and call. Membership in DPVCG is not necessary to contribute to DPV, but is recommended for participating in the group's decision making process. Contributions and questions can be sent to the group's [public mailing list](https://lists.w3.org/Archives/Public/public-dpvcg/) or expressed as [GitHub issues](https://github.com/dpvcg/dpv/issues).

## Suggesting new terms

To suggest a new term, we request following information:

> Please ensure the terms follow the [style guides](./documentation-generator/style-guide.md)
* _term_
* _description of the term_
* whether it should be a _class_ or _a property_
* relation to existing term(s) in DPV e.g. through sub-classes
* source (where applicable)
* justification or relevance of why this term should be added (where not obvious)

Suggestions are welcome via the group's meetings, mailing list, and GitHub issues.

## Raising issues

Before submitting an issue, please see the whether the issue has been addressed on [GitHub](https://github.com/w3c/dpv/issues). If not, please raise the issue via the group's [public mailing list](https://lists.w3.org/Archives/Public/public-dpvcg/) or expressed as [GitHub issues](https://github.com/w3c/dpv/issues).

Fixes, corrections to the terms are considered as issues and can be submitted similarly. For minor changes, we may prefer to incorporate them directly rather than through pull requests and patches. For larger issues, please check with the group before submitting a pull-request to ensure its appropriate and efficient incorporation.

## Development Guide

> (1) DO NOT change the outputs (HTML, RDF) directly - they are autogenerated from a different set of inputs
>
> (2) DO NOT make changes over the `main` branch - use the `dev` branch to make changes or raise PRs
The development and maintainence of DPV takes place primarily through shared spreadsheets (see [documentation-generator/vocab_csv](./documentation-generator/vocab_csv) folder). The terms and their annotated metadata are declared in the spreadsheet, and used as input to generate the RDF files and HTML documentation through the [documentation-generator](https://github.com/w3c/dpv/tree/master/documentation-generator) tooling. The `documentation` tool is a collection of Python scripts to assist in the automation of downloading the spreadsheet as CSV files, generating RDF files, validating them for correctness, and producing the HTML documentation.

Therefore, whenever adding a new term or changing existing ones, the following steps are recommended to update the DPV vocabulary and documentation:

1. Make changes appropriately in the shared spreadsheet. The links to this are available to the DPVCG members. For others, please see the CSV files in `documentation_generator/vocab_csv`. Ideally, create an GitHub issue for discussions and follow ups.
2. Use the [documentation-generator](./documentation-generator/) tooling to download the spreadsheet, generate RDF, test it, generate HTML output.
3. Manually inspect whether the changes have been made. Tools, scripts, and software in general can propogate errors silently.
4. The variables and parameters in [documentation-generator](https://github.com/w3c/dpv/tree/master/documentation-generator) tooling can be used to define the path where files are exported to can be set to the `dpv` repository to make changes in this directory. For e.g. `EXPORT_DPV_HTML_PATH = ~/code/dpvcg/dpv` will generate the HTML documentation in the `dpv` directory.
5. Submit a pull-request for merging with the repository.

## Getting help and assistance

If you're unsure about something, or would like clarifications, or suggestions - please communicate with us or open an issue. We would be happy to help.

0 comments on commit d5fc242

Please sign in to comment.