# Contribution Guide

This guide is intended for people who want to contribute to content of CodeMeta Git repository.

## Layout

The repository is laid out as such:

- `scripts/`: Python scripts to manipulate the crosswalk table.
- `properties_description.csv`: A CSV files with human-readable information about each CodeMeta property.
- `crosswalks/*.csv`: Two-column CSV files, that map between CodeMeta's properties and platform-specific terms.
- `crosswalk.csv`: An aggregated table of all CSV files mentioned above; intended to be the main resource for readers. Meant to be generated by a script and not be manually edited.

The repository has two major branches:

- `develop`: Any contribution that will change CodeMeta vocabulary should target this branch. Adding a new property, amending or removing an existing property will change the vocabulary.
- `master`: All other non-vocabulary changes, including mapping and crosswalk updates, should target this branch.
  - A minor amendment to a property *description* (not property *name* or *type* or *parent type*) can target this branch as well, as long as it does not change the semantic of the property.

## About pull requests

Do not commit changes to `crosswalk.csv`, as these will very likely create conflicts with other pull requests, and make either these PRs or yours unmergeable.

`crosswalk.csv` will be updated by repository maintainers when appropriate.

## Editing an existing mapping

1. Follow steps 1 and 2 from the "Contributing a new mapping" section below.
2. Open the CSV file in `crosswalks/` that contains the mapping you want to edit. You may change the second column (i.e. what comes after the comma on each line) to match the changes you want to make to the mapping.
3. Follow steps 4 onwards from the "Contributing a new mapping" section below.

## Contributing a new mapping

To add a new platform mapping to CodeMeta, you have to add a new CSV file to `crosswalks/`. Here are the instructions for doing so:

1. Fork the repository. This will create a copy of the codemeta repo in your own github profile.
2. Clone the codemeta repo that's in your github profile and continue working on it locally.
3. Create a new CSV file with your mapping in it in the `crosswalks/` folder. You could copy any other CSV file from `crosswalks/` to help you to write yours. The filename is free-form, but please avoid non-ASCII characters. The name is not used to build the aggregated table.
4. From the root of the repo, run `scripts/aggregate.py` using Python. This should involve something like opening a terminal, navigating to the root of the repo, and executing a command similar to the following: `python3 .\scripts\aggregate.py`. This will build an updated `crosswalk.csv` file using your new CSV file. You can open it up to check that it all looks good. This step is just to check that you haven't made any mistakes (such as editing the first column). You should not add the `crosswalk.csv` file to your commit. The real `crosswalk.csv` will be updated by a codemeta repo maintainer.
5. Commit your new CSV file with your mapping in it to the remote codemeta repo in your own github profile.
6. Go back to the original codemeta repo on the codemeta github profile. You should now see a yellow banner suggesting you open a "Compare & pull request". Click on this button (or navigate to Pull requests > New pull request). Add details of your new file/any changes you made and create the pull request.

## Adding a new CodeMeta property

1) **Adding the new property:**
To do so, you should first edit `properties_description.csv` and add a line with the appropriate cells there; and edit `codemeta.jsonld` as well.

2) **Update all existing mappings with the new property name:**
Add the new property name to each `crosswalks/*.csv` file, in the same position as in `properties_description.csv`.

3) **Test:**
Run `scripts/aggregate.py`. This will build the new `crosswalk.csv` with the new property; and raise an error if you made a mistake (such as editing the first column).

4) **Commit changes:**
You may then create a commit and send a pull request. Don't forget to **exclude** `crosswalk.csv` from the commit.