|
1 |
| -# Contributing |
| 1 | +# Contributing to CC Open Source |
2 | 2 |
|
3 |
| -There are two pieces to `og-image` that are worth noting before you begin development. |
| 3 | +Thank you for your interest in contributing to CC Open Source! This document is a set of guidelines to help you contribute to this project. |
4 | 4 |
|
5 |
| -1. The backend image generator located in [/api/index.ts](https://github.com/vercel/og-image/blob/main/api/index.ts) |
6 |
| -2. The frontend inputs located in [/web/index.ts](https://github.com/vercel/og-image/blob/main/web/index.ts) |
| 5 | +## Code of Conduct |
7 | 6 |
|
8 |
| -Vercel handles [routing](https://github.com/vercel/og-image/blob/main/vercel.json#L6) in an elegate way for us so deployment is easy. |
| 7 | +By participating in this project, you are expected to uphold our [Code of Conduct](https://opensource.creativecommons.org/community/code-of-conduct/). |
9 | 8 |
|
10 |
| -To start hacking, do the following: |
| 9 | +## Project Documentation |
11 | 10 |
|
12 |
| -1. Clone this repo with `git clone https://github.com/vercel/og-image` |
13 |
| -2. Change directory with `cd og-image` |
14 |
| -3. Run `yarn` or `npm install` to install all dependencies |
15 |
| -4. Run locally with `vercel dev` and visit [localhost:3000](http://localhost:3000) (if nothing happens, run `npm install -g vercel`) |
16 |
| -5. If necessary, edit the `exePath` in [options.ts](https://github.com/vercel/og-image/blob/main/api/_lib/options.ts) to point to your local Chrome executable |
| 11 | +Please consult the [README](./README.md) and [CODEBASE](./CODEBASE.md) files at the root of this repository. |
17 | 12 |
|
18 |
| -Now you're ready to start local development! |
| 13 | +## How to Contribute |
19 | 14 |
|
20 |
| -You can set an environment variable to assist with debugging `export OG_HTML_DEBUG=1`. This will render the image as HTML so you can play around with your browser's dev tools before committing changes to the template. |
| 15 | +Please read the processes in our general [Contributing Code](https://opensource.creativecommons.org/contributing-code/) guidelines on the Creative Common Open Source website. It contains some general instructions that should be followed when contributing to any of the Creative Commons open-source repositories. |
| 16 | + |
| 17 | +### Bugs |
| 18 | + |
| 19 | +If you find a bug, please open an issue in this repository describing the bug. You can file a bug [here](https://github.com/creativecommons/og-image-generator/issues/new?template=bug_report.md). You will see a bug report template with the required information you should provide. |
| 20 | + |
| 21 | +After that, don't forget to tag the issue with the "Bug" label. |
| 22 | + |
| 23 | +### Proposing changes or new features |
| 24 | + |
| 25 | +If you have an idea of a new feature or change to how the CC Search frontend works, please [file an issue](https://github.com/creativecommons/og-image-generator/issues/new?template=feature_request.md) so we can discuss the possibility of that change or new feature being implemented and released in the future. This lets us come to an agreement about the proposed idea before any work is done. |
| 26 | + |
| 27 | +If you'd like to build a new feature but don't have a specific idea, please check our [public roadmap](https://docs.google.com/document/d/19yH2V5K4nzWgEXaZhkzD1egzrRayyDdxlzxZOTCm_pc/). Choose something from the pipeline of ideas and follow the same process as above. |
| 28 | + |
| 29 | +### Pull requests |
| 30 | + |
| 31 | +Before you start writing code, make sure there is an issue open. Pull requests without a link to an existing issue won't be merged. All pull requests _must_ target the `develop` branch of the repository. |
| 32 | + |
| 33 | +If you want to get started contributing code to this project but don't know exactly what to work on, we compiled a good list of issues labeled as [Good first issues](https://github.com/creativecommons/og-image-generator/labels/good%20first%20issue) which are small in scope and not so complex to solve. There is also issues labeld as [Help wanted](https://github.com/creativecommons/og-image-generator/labels/help%20wanted) which can be a bit more complex but are good examples of thigns we are currently accepting help from the community. |
| 34 | + |
| 35 | +Any code modifications will have to be accompanied by the appropriate unit tests. This will be checked and verified during code review. Once the Pull Reques is opened, our CI server will run the unit test suite and run a code linter to verify that the code follows the coding guidelines. |
| 36 | + |
| 37 | +If you want to run the unit tests and linter on your machine, run the following commands: |
| 38 | + |
| 39 | +`npm run unit` for unit tests |
| 40 | + |
| 41 | +`npm run lint` for linter. |
| 42 | + |
| 43 | +You can also configure your editor of choice with a ESLint plugin so you can get the linter feedback as you write code. |
| 44 | + |
| 45 | +## Questions or Thoughts? |
| 46 | + |
| 47 | +Talk to us on [our developer mailing list or Slack community](https://opensource.creativecommons.org/community/). |
0 commit comments