diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index ddc1d075..4f1ea2ae 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -33,11 +33,28 @@ Contribution enquiries should take place before any significant pull request, otherwise you risk spending a lot of time working on something that we might have good reasons for rejecting. -## Pull requests +## Making Changes -Good pull requests - patches, improvements, new features - are a fantastic -help. They should remain focused in scope and avoid containing unrelated -commits. +If you'd like to test and/or contribute please follow these instructions. + +[Fork this repo on GitHub](https://github.com/twitter/twemoji.git/fork) + +### Setup + +```bash +# clone your fork +git clone -b master https://github.com/$YOUR_USERNAME/twemoji.git/ +cd twemoji + +# install dependencies +yarn install + +# Build and test your installation +yarn build +yarn test +``` + +### Making changes Make sure to adhere to the coding conventions used throughout the codebase (indentation, accurate comments, etc.) and any other requirements (such as test @@ -48,21 +65,37 @@ project: 1. Create a new topic branch to contain your feature, change, or fix: -2. Commit your changes in logical chunks. Provide clear and explanatory commit +> If you'd like to test and/or propose some changes to the latest library version please change the `./scripts/generate` file at its end so that everything will be generated properly once launched. + +1. Commit your changes in logical chunks. Provide clear and explanatory commit messages. Use git's [interactive rebase](https://help.github.com/en/articles/about-git-rebase) feature to tidy up your commits before making them public. -3. Locally merge (or rebase) the upstream development branch into your topic branch: +2. Run `yarn prepublish`. This will do several things: -4. Push your topic branch up to your fork: + 1. Ask for the version number (See: [SemVer](https://semver.org/)) + 2. Build the project and put the built assets in `dist/` + 3. Run the tests + 4. Move the contents of the `dist/` directory to the `gh-pages` branch + 5. Place the contents of the `dist/` directory in its correspoding versioned folder. + 6. Commit the changes and push them to the `gh-pages` branch of your fork. -5. [Open a Pull Request](http://help.github.com/send-pull-requests/) with a - clear title and description. +## Pull requests + +Good pull requests - patches, improvements, new features - are a fantastic +help. They should remain focused in scope and avoid containing unrelated +commits. + +1. Push your topic branch up to your fork: `git push origin my-feature-branch` + +2. [Open a Pull Request](http://help.github.com/send-pull-requests/) with a + clear title and description. One for your changes in `master` and another one for + your changes in `gh-pages`. ## License By contributing your code: You agree to license your contribution under the terms of the MIT (for code) and CC-BY (for graphics) licenses -https://github.com/twitter/twemoji/blob/gh-pages/LICENSE -https://github.com/twitter/twemoji/blob/gh-pages/LICENSE-GRAPHICS + + diff --git a/LEGACY.md b/LEGACY.md new file mode 100644 index 00000000..17b4e57e --- /dev/null +++ b/LEGACY.md @@ -0,0 +1,322 @@ +# Twemoji Legacy API (V1) + +## Usage + +### CDN Support + +The folks over at [MaxCDN](https://www.maxcdn.com) have graciously provided CDN support. + +Use the following in the `` tag of your HTML document(s): + +```html + +``` + +This guarantees that you are using the V1 version of the library. + +### Download + +If instead you want to download a specific version, please look at the `gh-pages` branch, where you will find the built assets for our legacy versions. + +## API + +Following are all the methods exposed in the `twemoji` namespace. + +### twemoji.parse( ... ) + +This is the main parsing utility and has 3 overloads per parsing type. + +There are mainly two kinds of parsing: [string parsing](https://github.com/twitter/twemoji#string-parsing) and [DOM parsing](https://github.com/twitter/twemoji#dom-parsing). + +Each of them accepts a callback to generate an image source or an options object with parsing info. + +Here is a walkthrough of all parsing possibilities: + +#### string parsing + +Given a generic string, replaces all emoji with an `` tag. + +While this can be used to inject emoji via image tags in `innerHTML`, please note that this method does not sanitize the string or prevent malicious code from being executed. As an example, if the text contains a ` ``` -## Breaking changes in V2 +This guarantees that you will always use the latest version of the library. -_TL;DR_: there's no `variant` anymore, all callbacks receive the transformed `iconId` and in some cases the rawText too. - -There are a few potentially breaking changes in `twemoji` version 2: - - * the `parse` invoked function signature is now `(iconId, options)` instead of `(icon, options, variant)` - * the `attributes` function now receives `(rawText, iconId)` instead of `(icon, variant)` - * the **default** remote protocol is now **https** regardless of whether the current site is _http_ or even _file_ - * the **default** PNG icon size is **72** pixels and **there are no other PNG assets** for 16 or 32. - * in order to access latest assets you need to specify *folder* `2/72x72` or `2/svg`. - -Everything else is pretty much the same, so if you were using the defaults, all you need to do is to add the version `2/` before the `twemoji.js` file you were using. +### Download +If instead you want to download a specific version, please look at the `gh-pages` branch, where you will find the built assets for both our latest and older versions. ## API @@ -49,99 +38,7 @@ Each of them accepts a callback to generate an image source or an options object Here is a walkthrough of all parsing possibilities: -##### string parsing (V1) -Given a generic string, replaces all emoji with an `` tag. - -While this can be used to inject emoji via image tags in `innerHTML`, please note that this method does not sanitize the string or prevent malicious code from being executed. As an example, if the text contains a `