[](https://github.com/GSA/ckanext-dcat_usmetadata/actions)
[](https://badge.fury.io/py/ckanext-dcat_usmetadata)
# ckanext-dcat_usmetadata
This extension provides a new dataset form for [inventory.data.gov](https://inventory.data.gov/). The form is tailored to managing metadata meeting the [DCAT-US Schema](https://resources.data.gov/resources/dcat-us/).
## Usage
### Dependencies
This module currently depends on the [USMetadata app](https://github.com/GSA/USMetadata) for server-side validation and rendering.
Make sure it is enabled in CKAN's plugins.
This extension is compatible with these versions of CKAN.
| CKAN version | Compatibility |
| ------------ | ------------- |
| >=2.9 | yes |
| >=3.0 | no |
### Installation
Add `ckanext-dcat-usmetadata` to your requirements.txt, and then pip install
In your CKAN .ini file add `dcat_usmetadata` to your enabled plugins:
`ckan.plugins = [YOUR PLUGINS HERE...] dcat_usmetadata`
### Commands
#### publishers-import
This extension adds a new CLI command for importing publishers linked to CKAN
organizations. The [list of
publishers](https://docs.google.com/spreadsheets/d/1BWpXWswnnMRaNazMCYrzl4W5JMWpGuyW0Wo2YaNH9jY/edit?usp=sharing)
should be exported in a CSV data and it should have the following structure
(note the headers):
```
organization,publisher,publisher_1,publisher_2,publisher_3,publisher_4,publisher_5
agricultural-marketing-service-department-of-agriculture,Department of Agriculture,Agricultural Marketing Service,,,,
ars-usda-gov,Department of Agriculture,Agricultural Research Service,,,,
aphis-usda-gov,Department of Agriculture,Animal and Plant Health Inspection Service,,,,
risk-management-agency-department-of-agriculture,Department of Agriculture,Departmental Management,,,,
usda-gov,Department of Agriculture,Office of Chief Information Officer,,,,
usda-gov,Department of Agriculture,Economic Research Service,,,,
usda-gov,Department of Agriculture,Farm Service Agency,,,,
usda-gov,Department of Agriculture,Food and Nutrition Service,,,,
usda-gov,Department of Agriculture,Food Safety and Inspection Service,,,,
usda-gov,Department of Agriculture,Foreign Agricultural Service,,,,
usda-gov,Department of Agriculture,National Agricultural Statistics Service,,,,
usda-gov,Department of Agriculture,National Institute of Food and Agriculture,,,,
usda-gov,Department of Agriculture,Natural Resources Conservation Service,Colorado State University,,,
usda-gov,Department of Agriculture,Rural Development,,,,
usda-gov,Department of Agriculture,GIPSA,Federal Grain Inspection Service,,,
usda-gov,Department of Agriculture,Natural Resources Conservation Service,,,,
usda-gov,Department of Agriculture,US Forest Service,,,,
```
Each CKAN organization must have its own list of publishers.
Example of running the command:
$ ckan dcat-usmetadata import-publishers /path/to/publishers.csv
## Development
### Prerequisites
These tools are required for development.
- [Node.js](https://nodejs.org/) 12.x
- [Yarn](https://yarnpkg.com/) 1.22.x
- [Cypress](https://www.cypress.io/) 6.0.0+
### Setup
Install Node.js dependencies.
```bash
yarn install
```
Build the JS application. The new build files can be found in `ckanext/dcat_usmetadata/public` folder.
- Pass the `--emptyOutDir` flag to replace an existing build.
```bash
yarn build
```
Build and start the docker containers.
```bash
yarn build:docker
yarn up
```
## Testing
There are several levels of testing:
| Suite | Description | Command |
| ------------------------- | ---------------------------- | ------------------------ |
| Unit tests for the JS app | Tests for the React app. | `yarn test:metadata-app` |
| CKAN extension tests | Python tests using Nosetests | `yarn test` |
| End to end tests | Cypress tests | `yarn e2e` |
## Linting
Lint the python code.
```bash
yarn lint:python
```
Lint the JavaScript code.
```bash
yarn lint:js
```
## Metadata app
The Metadata app was a [Create React App](https://create-react-app.dev/)-bootstrapped project converted to use [Vite](https://vitejs.dev/) as the build tool.
To run the app use `yarn && yarn start` command.
_TODO briefly describe how the metadata application relates to the CKAN
extension._
### Development
This project uses [cosmos](https://reactcosmos.org/) for development.
Run CKAN locally (`yarn up`), get the Admin user's API Key and add it in `/metadata-app/public/index.html` as `data-apiKey` attribute of the `div` element. Add a test org for development purposes.
Run `yarn && yarn cosmos` to start the cosmos server, which will watch the `metadata-app/src` directory for changes.
Run the unit tests:
```bash
yarn test:metadata-app
# To run it in watch mode:
yarn test:metadata-app:watch
```
### Update Jest snapshots
Some tests render a fixture component with [Jest](https://jestjs.io/) and then
match against a known good snapshot (HTML rendering) of the component. When you
edit a component, you'll usually have to update the snapshot and inspect the
diff to make sure all changes are as intended.
```bash
yarn test:metadata-app --updateSnapshot
```
## Local development and end-to-end testing
To build the latest JS code and update assets in the CKAN extension, you can run the following command from the root directory of this project:
```
yarn build
```
For convenience, we have prepared a single script that you can run to perform end-to-end tests locally. Don't forget to `yarn build` prior to running e2e tests, otherwise, the tests could run against older builds:
```bash
yarn e2e
```
Note, it may be necessary to remove cached images when rebuilding the docker container, in order to ensure that the new usmetadata-app template is included in the build. If you want to make sure that you aren't using cached builds, you can try:
```bash
docker-compose build --no-cache --pull ckanext-dcat_usmetadata_app
```
To run e2e tests interactively use:
```bash
yarn e2e:interactive
```
### Locally installing this extention
You can install this extension locally (to [inventory app](https://github.com/GSA/inventory-app), for example), but you must `yarn install` and then `yarn build` the JS/CSS prior to launching the app locally.
## Publishing a new version of the extension
We publish this extension to PyPI - https://pypi.org/project/ckanext-dcat-usmetadata/. This is done by CI job that is triggered on tagged commit on master branch. When you need to release a new version of the extension, you need to:
0. Create a new branch for releasing a new version of the extension. You can name your branch with the following convention: `release/x.y.z`;
1. Update version in `setup.py`;
2. Get your PR merged to master branch;
3. Tag the merged commit with the new version (`git tag $version`).
In the CI job, the following is done for tagged commits:
- It builds the JS bundles and puts them into the relevant directory so the extension can use them;
- It runs integration tests to make sure everything is working as expected;
- It packages the extension and publishes it to PyPI.
Below is a sequence diagram demonstrating the flow (you need to have `github + mermaid` chrome extension to view it):
```mermaid
sequenceDiagram
Developer->>Git: Push tagged commit to master branch
Git-->>CI/CD: Trigger deployment
CI/CD-->>CI/CD: Build assets (JS bundles)
CI/CD-->>CI/CD: Build python package
CI/CD-->>CI/CD: Run tests
CI/CD-->>PyPI: Publish the package
Inventory-->>PyPI: Install
```
## Ways to Contribute
The Data.gov team manages all Data.gov updates, bugs, and feature additions via GitHub's public [issue tracker](https://github.com/GSA/ckanext-dcat_usmetadata/issues) in this repository.
If you do not already have a GitHub account, you can [sign up for GitHub here](https://github.com/). In the spirit of open source software, everyone is encouraged to help improve this project. Here are some ways you can contribute:
- by reporting bugs
- by suggesting new features
- by translating content to a new language
- by writing or editing documentation
- by writing specifications
- by writing code and documentation (no pull request is too small: fix typos, add code comments, clean up inconsistent whitespace)
- by reviewing pull requests.
- by closing issues
### Submit Great Issues
- Before submitting a new issue, check to make sure a similar issue isn't already open. If one is, contribute to that issue thread with your feedback.
- When submitting a bug report, please try to provide as much detail as possible, i.e. a screenshot or gist that demonstrates the problem, the technology you are using, and any relevant links.
### Ready for your Help
Issues labeled [help wanted](https://github.com/GSA/data.gov/labels/help%20wanted) make it easy for you to find ways you can contribute today.
## Public Domain
This project constitutes a work of the United States Government and is not subject to domestic copyright protection under 17 USC ยง 105. Additionally, we waive copyright and related rights in the work worldwide through the CC0 1.0 [Universal public domain dedication](https://creativecommons.org/publicdomain/zero/1.0/).
All contributions to this project will be released under the CC0 dedication. By submitting a pull request, you are agreeing to comply with this waiver of copyright interest.
Raw data
{
"_id": null,
"home_page": "https://github.com/GSA/ckanext-dcat_usmetadata",
"name": "ckanext-dcat-usmetadata",
"maintainer": "",
"docs_url": null,
"requires_python": "",
"maintainer_email": "",
"keywords": "CKAN",
"author": "Data.gov",
"author_email": "datagovhelp@gsa.gov",
"download_url": "https://files.pythonhosted.org/packages/0e/51/84086012a3d6d4d8a3e1a1b340f8fcbc17646d093c708dac43a34098fc0a/ckanext-dcat_usmetadata-0.5.0.tar.gz",
"platform": null,
"description": "[](https://github.com/GSA/ckanext-dcat_usmetadata/actions)\n[](https://badge.fury.io/py/ckanext-dcat_usmetadata)\n\n# ckanext-dcat_usmetadata\n\nThis extension provides a new dataset form for [inventory.data.gov](https://inventory.data.gov/). The form is tailored to managing metadata meeting the [DCAT-US Schema](https://resources.data.gov/resources/dcat-us/).\n\n## Usage\n\n### Dependencies\n\nThis module currently depends on the [USMetadata app](https://github.com/GSA/USMetadata) for server-side validation and rendering.\nMake sure it is enabled in CKAN's plugins.\n\nThis extension is compatible with these versions of CKAN.\n\n| CKAN version | Compatibility |\n| ------------ | ------------- |\n| >=2.9 | yes |\n| >=3.0 | no |\n\n### Installation\n\nAdd `ckanext-dcat-usmetadata` to your requirements.txt, and then pip install\n\nIn your CKAN .ini file add `dcat_usmetadata` to your enabled plugins:\n\n`ckan.plugins = [YOUR PLUGINS HERE...] dcat_usmetadata`\n\n### Commands\n\n#### publishers-import\n\nThis extension adds a new CLI command for importing publishers linked to CKAN\norganizations. The [list of\npublishers](https://docs.google.com/spreadsheets/d/1BWpXWswnnMRaNazMCYrzl4W5JMWpGuyW0Wo2YaNH9jY/edit?usp=sharing)\nshould be exported in a CSV data and it should have the following structure\n(note the headers):\n\n```\norganization,publisher,publisher_1,publisher_2,publisher_3,publisher_4,publisher_5\nagricultural-marketing-service-department-of-agriculture,Department of Agriculture,Agricultural Marketing Service,,,,\nars-usda-gov,Department of Agriculture,Agricultural Research Service,,,,\naphis-usda-gov,Department of Agriculture,Animal and Plant Health Inspection Service,,,,\nrisk-management-agency-department-of-agriculture,Department of Agriculture,Departmental Management,,,,\nusda-gov,Department of Agriculture,Office of Chief Information Officer,,,,\nusda-gov,Department of Agriculture,Economic Research Service,,,,\nusda-gov,Department of Agriculture,Farm Service Agency,,,,\nusda-gov,Department of Agriculture,Food and Nutrition Service,,,,\nusda-gov,Department of Agriculture,Food Safety and Inspection Service,,,,\nusda-gov,Department of Agriculture,Foreign Agricultural Service,,,,\nusda-gov,Department of Agriculture,National Agricultural Statistics Service,,,,\nusda-gov,Department of Agriculture,National Institute of Food and Agriculture,,,,\nusda-gov,Department of Agriculture,Natural Resources Conservation Service,Colorado State University,,,\nusda-gov,Department of Agriculture,Rural Development,,,,\nusda-gov,Department of Agriculture,GIPSA,Federal Grain Inspection Service,,,\nusda-gov,Department of Agriculture,Natural Resources Conservation Service,,,,\nusda-gov,Department of Agriculture,US Forest Service,,,,\n```\n\nEach CKAN organization must have its own list of publishers.\n\nExample of running the command:\n\n $ ckan dcat-usmetadata import-publishers /path/to/publishers.csv\n\n## Development\n\n### Prerequisites\n\nThese tools are required for development.\n\n- [Node.js](https://nodejs.org/) 12.x\n- [Yarn](https://yarnpkg.com/) 1.22.x\n- [Cypress](https://www.cypress.io/) 6.0.0+\n\n### Setup\n\nInstall Node.js dependencies.\n\n```bash\nyarn install\n```\n\nBuild the JS application. The new build files can be found in `ckanext/dcat_usmetadata/public` folder.\n\n- Pass the `--emptyOutDir` flag to replace an existing build.\n\n```bash\nyarn build\n```\n\nBuild and start the docker containers.\n\n```bash\nyarn build:docker\nyarn up\n```\n\n## Testing\n\nThere are several levels of testing:\n\n| Suite | Description | Command |\n| ------------------------- | ---------------------------- | ------------------------ |\n| Unit tests for the JS app | Tests for the React app. | `yarn test:metadata-app` |\n| CKAN extension tests | Python tests using Nosetests | `yarn test` |\n| End to end tests | Cypress tests | `yarn e2e` |\n\n## Linting\n\nLint the python code.\n\n```bash\nyarn lint:python\n```\n\nLint the JavaScript code.\n\n```bash\nyarn lint:js\n```\n\n## Metadata app\n\nThe Metadata app was a [Create React App](https://create-react-app.dev/)-bootstrapped project converted to use [Vite](https://vitejs.dev/) as the build tool.\n\nTo run the app use `yarn && yarn start` command.\n\n_TODO briefly describe how the metadata application relates to the CKAN\nextension._\n\n### Development\n\nThis project uses [cosmos](https://reactcosmos.org/) for development.\n\nRun CKAN locally (`yarn up`), get the Admin user's API Key and add it in `/metadata-app/public/index.html` as `data-apiKey` attribute of the `div` element. Add a test org for development purposes.\n\nRun `yarn && yarn cosmos` to start the cosmos server, which will watch the `metadata-app/src` directory for changes.\n\nRun the unit tests:\n\n```bash\nyarn test:metadata-app\n# To run it in watch mode:\nyarn test:metadata-app:watch\n```\n\n### Update Jest snapshots\n\nSome tests render a fixture component with [Jest](https://jestjs.io/) and then\nmatch against a known good snapshot (HTML rendering) of the component. When you\nedit a component, you'll usually have to update the snapshot and inspect the\ndiff to make sure all changes are as intended.\n\n```bash\nyarn test:metadata-app --updateSnapshot\n```\n\n## Local development and end-to-end testing\n\nTo build the latest JS code and update assets in the CKAN extension, you can run the following command from the root directory of this project:\n\n```\nyarn build\n```\n\nFor convenience, we have prepared a single script that you can run to perform end-to-end tests locally. Don't forget to `yarn build` prior to running e2e tests, otherwise, the tests could run against older builds:\n\n```bash\nyarn e2e\n```\n\nNote, it may be necessary to remove cached images when rebuilding the docker container, in order to ensure that the new usmetadata-app template is included in the build. If you want to make sure that you aren't using cached builds, you can try:\n\n```bash\ndocker-compose build --no-cache --pull ckanext-dcat_usmetadata_app\n```\n\nTo run e2e tests interactively use:\n\n```bash\nyarn e2e:interactive\n```\n\n### Locally installing this extention\n\nYou can install this extension locally (to [inventory app](https://github.com/GSA/inventory-app), for example), but you must `yarn install` and then `yarn build` the JS/CSS prior to launching the app locally.\n\n## Publishing a new version of the extension\n\nWe publish this extension to PyPI - https://pypi.org/project/ckanext-dcat-usmetadata/. This is done by CI job that is triggered on tagged commit on master branch. When you need to release a new version of the extension, you need to:\n\n0. Create a new branch for releasing a new version of the extension. You can name your branch with the following convention: `release/x.y.z`;\n1. Update version in `setup.py`;\n2. Get your PR merged to master branch;\n3. Tag the merged commit with the new version (`git tag $version`).\n\nIn the CI job, the following is done for tagged commits:\n\n- It builds the JS bundles and puts them into the relevant directory so the extension can use them;\n- It runs integration tests to make sure everything is working as expected;\n- It packages the extension and publishes it to PyPI.\n\nBelow is a sequence diagram demonstrating the flow (you need to have `github + mermaid` chrome extension to view it):\n\n```mermaid\nsequenceDiagram\n Developer->>Git: Push tagged commit to master branch\n Git-->>CI/CD: Trigger deployment\n CI/CD-->>CI/CD: Build assets (JS bundles)\n CI/CD-->>CI/CD: Build python package\n CI/CD-->>CI/CD: Run tests\n CI/CD-->>PyPI: Publish the package\n Inventory-->>PyPI: Install\n```\n\n## Ways to Contribute\n\nThe Data.gov team manages all Data.gov updates, bugs, and feature additions via GitHub's public [issue tracker](https://github.com/GSA/ckanext-dcat_usmetadata/issues) in this repository.\n\nIf you do not already have a GitHub account, you can [sign up for GitHub here](https://github.com/). In the spirit of open source software, everyone is encouraged to help improve this project. Here are some ways you can contribute:\n\n- by reporting bugs\n- by suggesting new features\n- by translating content to a new language\n- by writing or editing documentation\n- by writing specifications\n- by writing code and documentation (no pull request is too small: fix typos, add code comments, clean up inconsistent whitespace)\n- by reviewing pull requests.\n- by closing issues\n\n### Submit Great Issues\n\n- Before submitting a new issue, check to make sure a similar issue isn't already open. If one is, contribute to that issue thread with your feedback.\n- When submitting a bug report, please try to provide as much detail as possible, i.e. a screenshot or gist that demonstrates the problem, the technology you are using, and any relevant links.\n\n### Ready for your Help\n\nIssues labeled [help wanted](https://github.com/GSA/data.gov/labels/help%20wanted) make it easy for you to find ways you can contribute today.\n\n## Public Domain\n\nThis project constitutes a work of the United States Government and is not subject to domestic copyright protection under 17 USC \u00a7 105. Additionally, we waive copyright and related rights in the work worldwide through the CC0 1.0 [Universal public domain dedication](https://creativecommons.org/publicdomain/zero/1.0/).\n\nAll contributions to this project will be released under the CC0 dedication. By submitting a pull request, you are agreeing to comply with this waiver of copyright interest.\n\n\n",
"bugtrack_url": null,
"license": "AGPL",
"summary": "DCAT USMetadata Form App for CKAN",
"version": "0.5.0",
"project_urls": {
"Homepage": "https://github.com/GSA/ckanext-dcat_usmetadata"
},
"split_keywords": [
"ckan"
],
"urls": [
{
"comment_text": "",
"digests": {
"blake2b_256": "7ec692b27336564026d2a5ff5af0c15e0e968ae6f40ecf15af25d150a569aaf7",
"md5": "bfb178cdeeee4f4bca6ba9bd1c9da9c6",
"sha256": "d69891a48f4c1cea80f1c2795f2abf48f60f8fa0abf89853313bfa86026b5ad3"
},
"downloads": -1,
"filename": "ckanext_dcat_usmetadata-0.5.0-py3-none-any.whl",
"has_sig": false,
"md5_digest": "bfb178cdeeee4f4bca6ba9bd1c9da9c6",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": null,
"size": 2644579,
"upload_time": "2023-07-28T23:15:16",
"upload_time_iso_8601": "2023-07-28T23:15:16.133772Z",
"url": "https://files.pythonhosted.org/packages/7e/c6/92b27336564026d2a5ff5af0c15e0e968ae6f40ecf15af25d150a569aaf7/ckanext_dcat_usmetadata-0.5.0-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": "",
"digests": {
"blake2b_256": "0e5184086012a3d6d4d8a3e1a1b340f8fcbc17646d093c708dac43a34098fc0a",
"md5": "e31ad4663d187db285564239efafd771",
"sha256": "7885b1cae6c98acecbc965ab90c74f862fc0ffe60e8884c7a390a6989004e21b"
},
"downloads": -1,
"filename": "ckanext-dcat_usmetadata-0.5.0.tar.gz",
"has_sig": false,
"md5_digest": "e31ad4663d187db285564239efafd771",
"packagetype": "sdist",
"python_version": "source",
"requires_python": null,
"size": 2566693,
"upload_time": "2023-07-28T23:15:18",
"upload_time_iso_8601": "2023-07-28T23:15:18.348890Z",
"url": "https://files.pythonhosted.org/packages/0e/51/84086012a3d6d4d8a3e1a1b340f8fcbc17646d093c708dac43a34098fc0a/ckanext-dcat_usmetadata-0.5.0.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2023-07-28 23:15:18",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "GSA",
"github_project": "ckanext-dcat_usmetadata",
"travis_ci": true,
"coveralls": true,
"github_actions": true,
"requirements": [],
"lcname": "ckanext-dcat-usmetadata"
}
JSON
