Skip to content
Website for clearlydefined.io
Branch: master
Clone or download
dabutvin Merge pull request #716 from dabutvin/other
introduce 'OTHER' as a choice for curating license
Latest commit 2bad145 May 20, 2019
Permalink
Type Name Latest commit message Commit time
Failed to load latest commit information.
.vscode Merge branch 'master' into webyourmind/e2eTests Feb 15, 2019
__mocks__ Unit and Integration test separation configuration Jan 22, 2019
config/jest Unit and Integration test separation configuration Jan 22, 2019
e2e Github selection e2e tests May 8, 2019
public Move to Font Awesome 5 Mar 19, 2018
src introduce 'OTHER' as a choice for curating license May 16, 2019
.babelrc Unit and Integration test separation configuration Jan 22, 2019
.dockerignore Don't copy node_modules into image Jan 22, 2018
.env .env configuration Oct 8, 2018
.env.development Update environment files to use REACT_APP_SERVER Oct 8, 2018
.env.localhost tweak env setup Oct 13, 2018
.env.production Update environment files to use REACT_APP_SERVER Oct 8, 2018
.eslintrc.json Removed console.logs Apr 3, 2019
.gitignore Adding back .env files to gitignore Oct 8, 2018
.nvmrc Add node version manager config file Feb 16, 2018
.prettierrc add prettier config and reformat everything Mar 3, 2018
CODE_OF_CONDUCT.md update copyrights etc Dec 18, 2017
CONTRIBUTING.md Manual 'repolint' at TODO hackathon - license and contribution info Feb 27, 2018
Dockerfile update file headers with new copyright and license text Mar 3, 2018
LICENSE Manual 'repolint' at TODO hackathon - license and contribution info Feb 27, 2018
README.md change how e2e tests are run Mar 8, 2019
azure-pipelines.yml Set up CI with Azure Pipelines Nov 21, 2018
jest.config.integration.js Unit and Integration test separation configuration Jan 22, 2019
jest.config.js Removed css from jest configuration Jan 30, 2019
jest.config.unit.js Removed css from jest configuration Jan 30, 2019
nginx.conf support HTML5 pushstate Mar 20, 2018
package-lock.json Moved to @clearlydefined/spdx library May 10, 2019
package.json Moved to @clearlydefined/spdx library May 10, 2019

README.md

ClearlyDefined Web App

This project implements the website for ClearlyDefined. It's a relatively straightforward React app that serves mainly as a portal to discover and curate project data managed by the ClearDefined service.

The doc has a guide to using the website to browse, inspect and curate data.

Getting started in the code

If you are interested in working on the code for the website, follow the steps below. If you want to get the whole ClearlyDefined infrastructure running on you machine, check out the system quick start guide.

  1. The site is based on React so you need to install NPM.
  2. Clone this repo using git clone https://github.com/clearlydefined/website.git or equivalent.
  3. Change to the website repo directory (e.g., cd <dir where you cloned website>)
  4. Run npm install
  5. Run npm start

This sequence will get the code for site, fetch all the prerequisites, build the site, start it running and open a browser on http://localhost:3000. You should see the ClearlyDefined website and be able to browse the data etc. If you login (top right corner), more functionality will light up.

This simple setup uses the development instance of the service. That may be highly volatile and will change without notice. Having said that, we use it all the time so you're probably good. If you want setup your own service (and crawler for that matter), use the simple local system setup guide that has only a few more steps and gets you running all of ClearlyDefined on you local machine.

Since you are not forced to consume only the local APIs, but you can even consume directly the remote development or production APIs, for the website repo only you are able to point out different APIs endpoints, depending on your needs, using different kinds of npm scripts: - npm start use the default environment, which is actually the DEV environment, and it refers to development APIs - npm run start:dev-api points out specifically to the development APIs - npm run start:local-api points out the local environment, which works only if the service repo is started - npm run start:prod-api points out specifically to the production APIs

Running e2e Tests

If you want to test the development running e2e tests, just simply run:

  • npm run e2e:test runs all the test that are saved into the folder e2e/tests/

You can write your own tests, just create a new file inside the e2e/tests/ folder. All e2e are written using jest and puppeteer.

Note that by default all the e2e tests runs checking the development website on https://dev.clearlydefined.io If you want to run test on your local environment, you should run:

  • npm start start the website as normal. Builds the application and starts it on localhost:3000
  • npm run e2e:test run all the test checking on http://localhost:3000

Contributing

This project welcomes contributions and suggestions, and we've documented the details in the contribution policy.

The Code of Conduct for this project is details how the community interacts in an inclusive and respectful manner. Please keep it in mind as you engage here.

Workareas

Responsiveness

Well, the title says it. The site is not particularly responsive. Somethings are ok, most are not. The use of large text editor areas makes things tough. We may need some alternative experiences or simply disable them in more constrained environments. Ideally mobile users would be able to at least browse and do rudimentary data entry. Even on desktops, users looking to dock half-screen windows to the side of their monitors may be a bit cramped.

Overall we need a design that talks about what is possible on different form-factors and user scenarios, and then a mess of work to make that happen.

Contribution workflow

Currently there are few affordances for a normal user to contribute a little bit of data for a component let alone anything for a component that is not already in the system.

  • YAML is ok to read but is less fun to create. Certainly for non-techies. Certainly without auto-complete and schema validation. Those could be added to the editors (there are issues for that) but it is still not the most approachable.
  • There is no story for contributing data for something that is not already “in the system”. You can’t pick it from the selection box for example. The only option is to queue it for harvesting. Harvest queuing is not exposed to the masses at this point.

We need a simple perhaps form-based experience where users can fill in the data they have and create whole new definition entries in the system. One idea is to enable some lightweight scanning that just does top level licenses, source location, etc. and populates the system. Then, at a later date, the full ScanCode style tools can be run and the data built out.

Understanding an optimal user experience for this will be key to making it compelling.

Implementation validation

The first version of the web app was written by React/Redux newbie (the author of this text so I can say that). While it may be ok, there are likely untold bad practices and less than optimal code patterns. Data management via Redux is likely one of the key culprits.

Having some folks who have a proven deep understanding Redux and React take a look at the setup and help it mature into a world-class React app would be fantastic.

You can’t perform that action at this time.