From f291bae3b67817811f09fafa0a792473d3d368ec Mon Sep 17 00:00:00 2001 From: Jason Date: Wed, 9 Jan 2019 20:44:12 +0000 Subject: [PATCH] Update readme and add issue templates (#359) * Updating the readme and contributing docs * add readme links * add issue templates * add bug and feature templates * update issue templates * fix markdown spacing in templates * update license so it is picked up by github * update readme links * fix license formatting --- .github/ISSUE_TEMPLATE/Feature_request.md | 24 ++++++ .github/ISSUE_TEMPLATE/bug_report.md | 48 ++++++++++++ CONTRIBUTING.md | 86 ++++++++++++++++++++ README.md | 96 +++-------------------- 4 files changed, 170 insertions(+), 84 deletions(-) create mode 100644 .github/ISSUE_TEMPLATE/Feature_request.md create mode 100644 .github/ISSUE_TEMPLATE/bug_report.md create mode 100644 CONTRIBUTING.md diff --git a/.github/ISSUE_TEMPLATE/Feature_request.md b/.github/ISSUE_TEMPLATE/Feature_request.md new file mode 100644 index 0000000000..0641b5c8bf --- /dev/null +++ b/.github/ISSUE_TEMPLATE/Feature_request.md @@ -0,0 +1,24 @@ +--- +name: Feature request +about: Suggest new features for the extension + +--- + +## Summary + + +## Motivation + + +## Additional context + diff --git a/.github/ISSUE_TEMPLATE/bug_report.md b/.github/ISSUE_TEMPLATE/bug_report.md new file mode 100644 index 0000000000..e006272ff7 --- /dev/null +++ b/.github/ISSUE_TEMPLATE/bug_report.md @@ -0,0 +1,48 @@ +--- +name: Bug report +about: Use this template for reporting a bug. + +--- + + + +## Description + + +## Steps to Reproduce + +1. step 1 +2. step 2 +3. ... + +**Expected behavior:** + + +**Actual behavior:** + + +**Versions** + + + +- Extension: 20xx-xx-xx +- Browser: +- OS: + +## Additional Information + diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md new file mode 100644 index 0000000000..573d52f259 --- /dev/null +++ b/CONTRIBUTING.md @@ -0,0 +1,86 @@ +# Contributing guidelines + +# Reporting broken sites + +Report broken websites using the "Report Broken Site" link on the extension popup. + +# Reporting bugs + +1. First check to see if the bug has not already been [reported](https://github.com/duckduckgo/duckduckgo-privacy-extension/issues). +2. Create a bug report [issue](https://github.com/duckduckgo/duckduckgo-privacy-extension/issues/new?template=bug_report.md). + +# Feature requests + +There are two ways to submit feedback: +1. You can send anonymous feedback using the "Send feedback" link on the extension's options page. +2. You can submit your request as an [issue](https://github.com/duckduckgo/duckduckgo-privacy-extension/issues/new?template=feature_request.md). First check to see if the feature has not already been [suggested](https://github.com/duckduckgo/duckduckgo-privacy-extension/issues). + +# Development + +## New features + +Right now all new feature development is handled internally. + +## Bug fixes + +Most bug fixes are handled internally, but we will except pull requests for bug fixes if you first: +1. Create an issue describing the bug. see [Reporting bugs](CONTRIBUTING.md#reporting-bugs) +2. Get approval from DDG staff before working on it. Since most bug fixes and feature development are handled internally, we want to make sure that your work doesn't conflict with any current projects. + +## Testing locally + +### Pre-Requisites +- [Node.js](https://nodejs.org) installation +- [Grunt](https://www.npmjs.com/package/grunt) +- Tests use [Selenium Webdriver](http://seleniumhq.github.io/selenium/docs/api/javascript/index.html). + +### Building the extension +- Firefox + 1. Run `npm run dev-firefox` + 2. Load the extension in Firefox from the `build/firefox/dev` directory +[Temporary installation in Firefox - Mozilla | MDN](https://developer.mozilla.org/en-US/Add-ons/WebExtensions/Temporary_Installation_in_Firefox) + +- Chrome + 1. Run `npm run dev-chrome` + 2. Load the extension in Chrome from the `build/chrome/dev` directory +[Getting Started: Building a Chrome Extension - Google Chrome](https://developer.chrome.com/extensions/getstarted#unpacked) + +- Safari + + The Safari extension is no longer supported. + +### Development flow + +The `shared` directory contains JS, CSS, and images that are shared by all browsers. + +The popup UI is in `shared/js/ui` + +The background JS is in `shared/js/` + +Browser specific files, including manifest files, are located in `browsers/` + +Run the dev build task for your browser from the 'Build' section above. The generated build files are located in `/build//dev`. + +After running the build task it will continue watching for changes to any of the source files. After saving any changes to these files it will automatically rebuild the `dev` directory for you. + +### Testing +- Unit tests: `npm test` +- Integration Tests + - Local, requires Chrome: `npm run test-int` + - Headless, requires xvfb: `npm run test-ci` + +### Selenium Testing (ratings.js) + +**Setup** + +1. For remote linux machine, first setup xvfb: `source selenium-test/setup.sh` +2. `npm install` +3. `grunt` + +**Testing Single Site** `./selenium-test/ratings.js -u https://website.com` + +**Testing Top 500** `./selenium-test/ratings.js -n 2` (where n = [1 - 500]) + +**Testing Multiple Sites** `./selenium-test/ratings.js -f urls.txt` (file should have 1 url on each line) + +**Using XVFB** To test on a remote server with XVBF installed, add `-x` flag: `./selenium-test/ratings.js -x -u https://website.com` diff --git a/README.md b/README.md index f97f46d8ea..3cdb83fd2a 100755 --- a/README.md +++ b/README.md @@ -2,99 +2,27 @@ [![Build Status](https://travis-ci.org/duckduckgo/duckduckgo-privacy-extension.svg?branch=develop)](https://travis-ci.org/duckduckgo/duckduckgo-privacy-extension) -DuckDuckGo Firefox, Chrome, and Safari extensions +DuckDuckGo Firefox and Chrome extensions -This software is licensed under the terms of the Apache License, Version 2.0 (see LICENSE). Copyright (c) 2012 - 2017 [duckduckgo.com](https://duckduckgo.com) +This software is licensed under the terms of the Apache License, Version 2.0 (see [LICENSE](LICENSE)). Copyright (c) 2012 - 2019 [duckduckgo.com](https://duckduckgo.com) -## Pre-Requisites -- [Node.js](https://nodejs.org) installation -- Tests use [Selenium Webdriver](http://seleniumhq.github.io/selenium/docs/api/javascript/index.html) and require: +## Latest Versions -## Set up development environment -- `npm install` from root directory +[Firefox](https://addons.mozilla.org/en-US/firefox/addon/duckduckgo-for-firefox/) -## Build -- Firefox: - `npm run dev-firefox` - Load the extension in Firefox from the `build/firefox/dev` directory -[Temporary installation in Firefox - Mozilla | MDN](https://developer.mozilla.org/en-US/Add-ons/WebExtensions/Temporary_Installation_in_Firefox) +[Chrome](https://chrome.google.com/webstore/detail/duckduckgo-privacy-essent/bkdgflcldnnnapblkhphbgpggdiikppg) -- Chrome: - `npm run dev-chrome` - Load the extension in Chrome from the `build/chrome/dev` directory -[Getting Started: Building a Chrome Extension - Google Chrome](https://developer.chrome.com/extensions/getstarted#unpacked) +## Reporting a broken site -- Safari: -`npm run dev-safari` +Report broken sites using the anonymous "Report Broken Site" link in the extension popup. -Load the extension in Safari from the `build/duckduckgo.safariextension/dev/duckduckgo.safariextension` directory using the [extension builder](https://developer.apple.com/library/content/documentation/Tools/Conceptual/SafariExtensionGuide/UsingExtensionBuilder/UsingExtensionBuilder.html) +## Reporting bugs - -## Development flow -Shared JS, CSS, and images are located in the `shared` directory. - -Popup: `shared/js/ui` -Background: `shared/js/` - -Browser specific files, including manifest files, are located in `browsers/` - -Run the dev build task for your browser from the 'Build' section above. The build files are located in `/build//dev`. Point your browser to this location to load the extension: - -After running the build task it will continue watching for changes to any of the source files. After saving any changes to these files it will automatically rebuild the `dev` directory for you. - -## Testing -- Unit tests can be run from the dev version of the extension by going to -Firefox: `moz-extension://` - -### Chrome -- Update the manifest version in `browsers/chrome/manifest.json` -- Build a release version: `npm run release-chrome` -- Test `build/chrome/release` locally -- A date versioned zip file is automatically built `build/chrome/release/chrome-release-YYYYMMDD-hhmmss.zip` -- Merge the release branch into master -- Upload the zip file to the Chrome store -### Firefox -- Update the manifest version in `browsers/firefox/manifest.json` -- Build a release version: `npm run release-firefox` -- Test `build/firefox/release` locally -- Merge the release branch to master -- Move to the release directory: `cd build/firefox/release` -- Use `web-ext` to package, sign, and upload to the Firefox Addon store -- `web-ext sign --api-key=$JWT_ISSUER --api-secret=$JWT_SECRET` +We're not accepting new feature pull requests right now. For bug fixes see [Development](CONTRIBUTING.md#development) -### Safari -- Update the version numbers in `browsers/duckduckgo.safariextension/Info.plist`. You need to update both `CFBundleVersion` and `CFBundleShortVersionString`. -- Build a release version. Follow the same build steps from the build section above. Use `npm run dev-safari`. -- Test locally -- Before building a package with Safari extension builder you need to clear your company stats and localStorage otherwise your data will be packaged in the release version. -In the extension console run `localStorage.clear()` and `Companies.resetData()`. -- Build a package through the extension builder. +## Questions or help with the search engine +See [help pages](https://duck.co/help)