Merge pull request #160 from ndaidong/improve-docs

Improve docs

.github/workflows/ci-test.yml

@@ -15,10 +15,10 @@ jobs:
         node_version: [14.x, 15.x, 16.x, 17.x, 18.x, 19.x]
 
     steps:
-    - uses: actions/checkout@v2
+    - uses: actions/checkout@v3
 
     - name: setup Node.js v${{ matrix.node_version }}
-      uses: actions/setup-node@v1
+      uses: actions/setup-node@v3
       with:
         node-version: ${{ matrix.node_version }}
 
@@ -38,7 +38,7 @@ jobs:
         github-token: ${{ secrets.GITHUB_TOKEN }}
 
     - name: cache node modules
-      uses: actions/cache@v2
+      uses: actions/cache@v3
       with:
         path: ~/.npm
         key: ${{ runner.os }}-node-${{ hashFiles('**/package-lock.json') }}

CONTRIBUTING.md

@@ -0,0 +1,87 @@
+# Contributing to oembed-parser
+
+While `oembed-parser` is just a simple library with personal purpose, I'm happy if it can be useful for you too.
+
+Anyway, I hope it always gets better, so pull requests are welcome, though larger proposals should be discussed first.
+
+As an OSS, it should follow the Unix philosophy: "do one thing and do it well".
+
+## Installation
+
+- Ensure you have `node` and `npm` installed.
+- After cloning the repository, run `npm install` in the root of the repository.
+- Run `npm test` to ensure that everything works correctly in your environment.
+
+Because test suite includes the cases of Facebook/Instagram oembed link, you need to set the environment variables `FACEBOOK_APP_ID` and `FACEBOOK_CLIENT_TOKEN`.
+Otherwise the test will fail. Please refer [this section](https://github.com/ndaidong/oembed-parser#facebook-and-instagram) for more info.
+
+Once it works well, you can start modifying your fork.
+
+In this process, you can use [`npm run eval` command](https://github.com/ndaidong/oembed-parser#quick-evaluation) to evaluate your changes.
+
+
+## Third-party libraries
+
+Please avoid using libaries other than those available in the standard library, unless necessary.
+
+This library needs to be simple and flexible to run on multiple platforms such as Deno, Bun, or even browser.
+
+
+## Coding convention
+
+Please follow [standardjs](https://standardjs.com/) style guide.
+
+Make sure your code lints before opening a pull request.
+
+
+```bash
+cd oembed-parser
+
+# check coding convention issue
+npm run lint
+
+# auto fix coding convention issue
+npm run lint:fix
+```
+
+*When you run `npm test`, the linting process will be triggered at first.*
+
+
+## Testing
+
+Be sure to run the unit test suite before opening a pull request. An example test run is shown below.
+
+```bash
+cd oembed-parser
+npm test
+```
+
+![oembed-parser unit test](https://i.imgur.com/Nr5BgUx.png)
+
+If test coverage decreased, please check test scripts and try to improve this number.
+
+
+## Documentation
+
+If you've changed APIs, please update README and [the examples](https://github.com/ndaidong/oembed-parser/tree/main/examples).
+
+
+## Clean commit histories
+
+When you open a pull request, please ensure the commit history is clean.
+Squash the commits into logical blocks, perhaps a single commit if that makes sense.
+
+What you want to avoid is commits such as "WIP" and "fix test" in the history.
+This is so we keep history on master clean and straightforward.
+
+For people new to git, please refer the following guides:
+
+- [Writing good commit messages](https://github.com/erlang/otp/wiki/writing-good-commit-messages)
+- [Commit Message Guidelines](https://gist.github.com/robertpainsi/b632364184e70900af4ab688decf6f53)
+
+
+## License
+
+By contributing to `oembed-parser`, you agree that your contributions will be licensed under its [MIT license](https://github.com/ndaidong/oembed-parser/blob/main/LICENSE).
+
+---

README.md

@@ -224,6 +224,17 @@ export FACEBOOK_CLIENT_TOKEN=your_client_token
 npm run eval https://www.instagram.com/tv/CVlR5GFqF68/
 ```
 
+
+## Quick evaluation
+
+```bash
+git clone https://github.com/ndaidong/oembed-parser.git
+cd oembed-parser
+npm i
+
+npm run eval {URL_TO_PARSE_OEMBED}
+```
+
 ## License
 The MIT License (MIT)