CONTRIBUTING.md

Contributing

Thanks for contributing to this project. Feel free to:

• report a bug
• wish a new feature
• fix a reported problem
• translate in to your language or fix missing translations
• improve the documentation
• get in touch

Translate

We use Transifex as online translation service. Have a look at Transifex project page. You can register as translator for free. It will automatically accept requests from translators to join the team.

Update translation in code

Open Transifex language overview page and select your language to update. Choose the i18n.json resource and click the link Download for use or Download only reviewed translations. Copy the downloaded file to folder

/static/assets/lang/

and rename it to {language code}.json.

If you change the en.json you must copy the file to /user-config/i18n/i18n.json and change the format from STRUCTURED_JSON to FLAT_JSON.

"button": {
  "string": "Start search",
  "developer_comment": "Catalog > Search Bar > button"
}

=>

"button": "Start search"

Provide code

You can provide bug fixes and new code. First of all, setup your environment.

Project Setup

Prepare your system and install nvm, the version manager for node.js.

Install Node.js v15.14.0+ and NPM 7.7.6+ on your system. Yes, this repo use older version of node.js. You are welcome to drop a merge request with updated packages.

$ nvm use 16
Now using node v16.14.0 (npm v8.3.1)
$ node -v
v16.14.0

Clone or download the code:

git clone [email protected]:opendata-guru/peacock-user-ui.git

Install NPM packages:

cd peacock-user-ui
npm install

Build steps

Build for Development

Open a terminal and run:

npm run dev

This will start a local webserver on Port 8084. Open a web browser and visit http://localhost:8084 to see the app.

Hot Module Replacement is supported. The page will update automatically whenever files are changed and saved.

Build for Production

Open a terminal and run:

npm run build

This will optimize files for production and store the bundle in peacock-user-ui/dist

Publish a new version to NPM

First of all check if you can create a production build successfully.

npm run build

Then check that all tests run without any errors and code coverage is as high as possible.

npm run test
npx jest --coverage

Remove all known security vulnerabilities. Get the audit report:

npm audit

Open package.json file and increase the version number of the package:

"version": "1.1.#",

Build the final production build:

npm run build

Follow next steps:

• format dist/js/config.js with [https://webformatter.com/javascript](JavaScript Formatter)
• push all changes to github
• draft a new release

Publishing a new release will automatically:

• create new downloadable ZIP files of source code on github
• publish a new version to npm
• publish a new version to CDN unpkg.com

Configurations

glue-config.js

The glue-config.js file is located at peacock-user-ui/user-config/glue-config.js. It is the main project configuration file. **But it contains default values only (and some very old values that should be removed in future).

You need to rebuild the project after changing this file.

user-configs.js

The user-configs.json file is located at peacock-user-ui/config/user-configs.js. It contains the paths to the glue-config.js and i18n.json. So this file overwrite the settings in glue-config.js.

The user-configs.js checks global variables and set the values, if set, to the configuration. The global variables can set in config.jsfile.

You need to rebuild the project after changing this file.

config.js

The config.js file is located at peacock-user-ui/static/js/config.js. Use this file to customize all settings for this project.

You does not need to rebuild the project after changing this file. But you must reload the browser while hot reloading does not work.

All settings described in README.md file.

Write own adapter

Write your own adapter with up to 5 files. Import your adapter files in user-configs.js file:

// Import Adapters for data requests
import datasetService from '../src/my-adapter-folder/myDatasetService';
import catalogueService from '../src/my-adapter-folder/myCatalogueService';
import distributionService from '../src/my-adapter-folder/myDistributionService';
import datastoreService from '../src/my-adapter-folder/myDatastoreService';
import gazetteerService from '../src/my-adapter-folder/myGazetteerService';

// Exported Config-Object
export default {
  // The services fetch data from somewhere. Each service has to be imported at the beginning of this file.
  services: {
    catalogueService,
    datasetService,
    distributionService,
    datastoreService,
    gazetteerService,
  },
};