Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Create documentation for Circle CI #2713

Closed
antross opened this issue Jul 22, 2019 · 3 comments · Fixed by #3124
Assignees
Milestone

Comments

@antross
Copy link
Member

@antross antross commented Jul 22, 2019

Need to copy paste on a markdown file and put it on the hint repo.


Specifically this should include example Circle CI configurations demonstrating how to use webhint.

@antross antross modified the milestone: 1908-1 Jul 22, 2019
@antross antross changed the title Create extension for Circle CI Create documentation for Circle CI Aug 2, 2019
@antross antross modified the milestones: 1908-1, 1908-2 Aug 2, 2019
@sarvaje

This comment has been minimized.

Copy link
Member

@sarvaje sarvaje commented Aug 12, 2019

As in travis, for CircleCI we just need to follow these steps:

  1. Install webhint as a devDependency - npm install hint --save-dev
  2. Add to your current test script in your package.json && hint ./
  3. Add the file .circleci/config.yml with this configuration:
version: 2.1
jobs:
  build:
    docker: 
      - image: circleci/node:10.16.2 # the primary container, where your job's commands are run
    steps:
      - checkout # check out the code in the project directory
      - run: npm install
      - run: npm run test

Until #2800 is merged and published, the step 1 should be npm install hint @hint/configuration-development --save-dev, and you should create a .hintrc in his project extending development

{
    "extends": ["development"]
}
@sarvaje

This comment has been minimized.

Copy link
Member

@sarvaje sarvaje commented Aug 28, 2019

I'm adding a list of scenarios we want to consider for the documentation:

Here is a initial list, please, feel free to update the list:

Scanning the project locally

  • Webhint is not part of the project (Maybe the project is not nodejs)
  • Webhint in the package.json.

Scanning the project "online" (for example, pre-production)

  • Webhint is not part of the project (Maybe the project is not nodejs)
  • Webhint in the package json.

Common

  • Using custom .hintrc.
  • Enabling telemetry.
  • How to avoid the cli to fail
  • How to collect the scan result

@webhintio/core ideas?

@sarvaje

This comment has been minimized.

Copy link
Member

@sarvaje sarvaje commented Aug 29, 2019

Locally

Webhint is in the package.json

Run in your project.

npm install hint --save--dev

In the file package.json add a new script test-hint:

...
"scripts": {
    ...
    "test-hint": "hint ./" // ./ or the path where the files to test are.
  }
...

Add the file .circleci/config.yml to your project:

version: 2.1
jobs:
  build:
    docker: 
      - image: circleci/node:lts
    steps:
      - checkout # check out the code in the project directory
      - run: npm install
      - run: npm run test-hint

Note: In this case hint will use as default configuration configuration-development if a .hintrc file is not present.

Project in another language or not included in the package.json

When your project is not a nodejs project or you just doesn't want to/can modify your package.json you can do:

Add a .circleci/config.yml to your project:

version: 2.1
jobs:
  build:
    docker: 
      - image: circleci/python:latest-node
    steps:
      - checkout # check out the code in the project directory
      - run: npm install hint --no-save
      - run: node node_modules/hint/dist/src/bin/hint.js ./ # ./ or the path where the files to test are.

In this case, we need nodejs to be install in the image. For the built-in images in circleci, you just need to add -node to the image tag, if you are using your own image, you need to update it to include nodejs. Once we have node in the image, we can install hint manually and run the scan.

As in the previous example, the default configuration will be configuration-development.

Online

Webhint is in the package.json

Run in your project.

npm install hint --save--dev

In the file package.json add a new script test-hint:

...
"scripts": {
    ...
    "test-hint": "hint https://url-to-your-project" // ideally, this url will be to your staging/preproduction environment.
}
...

Add the file .circleci/config.yml to your project:

version: 2.1
jobs:
  build:
    docker: 
      - image: circleci/node:lts-browsers
    steps:
      - checkout # check out the code in the project directory
      # Add the necessary steps to deploy your website.
      - run: npm install
      - run: npm run test

Note: In this case hint will use as default configuration configuration-web-recommended if a .hintrc file is not present.

Note: configuration-web-recommended use by default the connector puppeteer which requires a "chromium" browser to work. In you are using a circleci built-in image, you just need to add -browsers to the tag to have browsers installed. If you are using you custom image, you need to install a chromium browser in your image first.

Project in another language or hint not included in the package.json

When your project is not a nodejs project or you just doesn't want to/can modify your package.json you can do:

Add the file .circleci/config.yml to your project:

version: 2.1
jobs:
  build:
    docker: 
      - image: circleci/python:latest-node-browsers
    steps:
      - checkout # check out the code in the project directory
      # Add the necessary steps to deploy your website.
      - run: npm install hint --no-save
      - run: node node_modules/hint/dist/src/bin/hint.js https://url-to-your-project

The default configuration in this case will be configuration-web-recommended

As you can notice, if you need nodejs + browsers in your circleci image, you just need to add -node-browsers to the image tag. If you are using a custom image, you will need to install node and a chromium browser in you image.

Common

Enabling telemetry

To enabling telemetry you have a couple of options:

  1. By parameter. You need to add the parameter to the script to your package.json
    "scripts": {
        
        "test-hint": "hint https://webhint.io --debug --tracking=on"
      },
    …
    or in you .circleci/config.yml:
    version: 2.1
    jobs:
      build:
        docker: 
          - image: circleci/python:latest-node-browsers
        steps:
          - checkout # check out the code in the project directory
          # Add the necessary steps to deploy your website.
          - run: npm install hint --no-save
          - run: node node_modules/hint/dist/src/bin/hint.js https://url-to-your-project --tracking=on
  2. By env variable. You need to configure the env variable HINT_TRACKING in your file .circleci/config.yml:
    version: 2.1
    jobs:
      build:
        docker: 
          - image: circleci/node:lts-browsers
        steps:
          - checkout # check out the code in the project directory
          - run: echo 'export HINT_TRACKING="on"' >> $BASH_ENV
          - run: npm install
          - run: npm run test-hint

Using custom .hintrc

About how to use your custom .hintrc file, I think we should link to the documentation where we talk about it.

How to avoid the cli to fail

This can be part of "using custom .hintrc. By default hints are configured as error, this will make the CI to fail. If the user wants to continue the CI even if hint is reporting hints, the severity of the issues needs to be warning.

How to collect the scan result

By default, we are generating an html report.
image

I'm not sure if we can access to a CI "machine" after it finish, but maybe there is a way to get that content and publish it somewhere. This would need more investigation.

@antross antross modified the milestones: 1908-2, 1909-1 Aug 30, 2019
@antross antross modified the milestones: 1909-1, 1909-2 Sep 14, 2019
@molant molant modified the milestones: 1909-2, 1910-1 Sep 26, 2019
@molant molant modified the milestones: 1910-1, 1910-2 Oct 11, 2019
molant added a commit to molant/hint that referenced this issue Oct 16, 2019
@molant molant referenced this issue Oct 16, 2019
3 of 3 tasks complete
@molant molant assigned molant and unassigned hxlnt Oct 16, 2019
@molant molant modified the milestones: 1910-2, 1911-1 Oct 25, 2019
antross added a commit that referenced this issue Oct 29, 2019
Fix #2713
Fix #2776
Close #3124 

Co-Authored-By: Rachel Simone Weil <partytimehexcellent@gmail.com>
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Projects
None yet
4 participants
You can’t perform that action at this time.