From 88719890cf89bdaf1140d6f8a10f75e7376cab7b Mon Sep 17 00:00:00 2001 From: Swashata Ghosh Date: Fri, 13 Sep 2024 20:22:55 +0530 Subject: [PATCH] [doc] [contributing] Update doc and contributing guidelines. --- .github/workflows/ci.yaml | 2 +- CONTRIBUTING.md | 137 ++++++++++++++++++++++++++++++++++++ README.md | 44 ++++-------- cypress/support/commands.ts | 2 +- cypress/support/e2e.ts | 4 +- package.json | 4 +- prettier.config.js | 15 ++-- 7 files changed, 166 insertions(+), 42 deletions(-) diff --git a/.github/workflows/ci.yaml b/.github/workflows/ci.yaml index 3e8d53e..317a116 100644 --- a/.github/workflows/ci.yaml +++ b/.github/workflows/ci.yaml @@ -10,7 +10,7 @@ jobs: - uses: actions/checkout@v4 - uses: ./.github/actions/setup-node - name: Check code formatting - run: npx prettier --check ./src + run: npm run prettier:check eslint: name: ESLint diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index e69de29..75dd60c 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -0,0 +1,137 @@ +# Contributing to Freemius Checkout JS + +🎉 Thank you for your interest in contributing to **Freemius Checkout JS**! We +welcome contributions of all kinds, including code, documentation, issues, and +discussions. Please read through these guidelines to ensure a smooth +contribution process. 🎉 + +## Table of Contents + +- [Code of Conduct](#code-of-conduct) +- [How Can I Contribute?](#how-can-i-contribute) + - [Issues](#issues) + - [Pull Requests (PRs)](#pull-requests) + - [Discussions](#discussions) +- [Development Workflow](#development-workflow) +- [Style Guide](#style-guide) + - [Prettier Configuration](#prettier-configuration) +- [License](#license) + +## Code of Conduct + +By participating in this project, you agree to abide by the +[Contributor Covenant Code of Conduct](https://www.contributor-covenant.org/version/2/1/code_of_conduct/). +We aim to create a welcoming and inclusive community where everyone can +contribute, regardless of experience or background. + +## How Can I Contribute? + +### Issues + +If you find a bug or have a feature request, feel free to open an issue. Make +sure to provide enough details to help others understand and reproduce the +issue. + +1. Search existing issues before opening a new one to avoid duplicates. +2. Use a clear and descriptive title. +3. If you're reporting a bug, include steps to reproduce the problem, expected + behavior, and the actual outcome. + +### Pull Requests + +We encourage you to contribute to the codebase by submitting a pull request +(PR). Here's the process: + +1. **Fork the repository**: Fork the repo and clone it to your local machine. +2. **Branch from `develop`**: All contributions should be based on the `develop` + branch. + - Run `git checkout develop` and create a new branch with a meaningful name: + ```bash + git checkout develop + git checkout -b feature/new-awesome-feature + ``` +3. **Make your changes**: Write clean, efficient, and well-documented code. +4. **Run tests**: Ensure that all tests pass before submitting. +5. **Submit your PR**: Push your changes to your fork and create a pull request + against the `develop` branch. Include a detailed description of what your PR + does and reference related issues if applicable. + - We will review the PR as soon as possible. You may be asked to make + revisions based on feedback. + +### Discussions + +We welcome ideas and discussions! If you'd like to talk about future +improvements, ideas for new features, or general questions, feel free to start a +[discussion](https://github.com/Freemius/freemius-checkout-js/discussions). + +## Development Workflow + +1. **Set up the project**: + + - Clone your fork of the repository and install dependencies: + ```bash + git clone https://github.com/YOUR-USERNAME/freemius-checkout-js.git + cd freemius-checkout-js + npm ci + ``` + - Create the `.env` file and set the required environment variables: + ```bash + cp .env.sample .env.development.local + ``` + If you're a Freemius team member, you will find it useful to set the + `VITE_CHECKOUT_BASE_URL` to the internal development URL. See + [vite documentation](https://vitejs.dev/guide/env-and-mode.html#env-files) + to learn about how `.env` files are handled. + - Run the development server: + ```bash + npm run dev + ``` + The development server will start at `http://localhost:5173/`. + +2. **Work on your feature or fix**: + + - Make sure to work in your feature branch created from `develop`. + - Follow the coding standards and practices of the project. + +3. **Testing**: + + - Run tests to ensure nothing is broken: + ```bash + npm test + ``` + - Write new tests if you're adding a new feature or fixing a bug. + +4. **Running Linters**: Ensure that your code adheres to the project's style + guide. + + ```bash + npm run lint + npm run prettier:check + ``` + + If you do not have Prettier configured to format your code on save, you can + run `npm run prettier:write` to format your code. + +5. **Submit your work**: + - After your work is complete, create a pull request as outlined above. + +## Style Guide + +We follow standard **JavaScript** coding conventions and aim to keep our +codebase consistent. Please ensure that your contributions conform to these +standards: + +- Use **ES6** syntax where applicable. +- Use **4 spaces for indentation**. +- Write meaningful commit messages. +- Keep code modular and documented. + +### Prettier Configuration + +We use **Prettier** to enforce consistent code formatting. The project uses **4 +spaces for indentation**. To ensure that your contributions adhere to our style, +please configure Prettier to automatically format your code on save. + +- [PHPStorm](https://www.jetbrains.com/help/phpstorm/prettier.html) extension. +- [VSCode](https://marketplace.visualstudio.com/items?itemName=esbenp.prettier-vscode) + extension. diff --git a/README.md b/README.md index e7cb672..c8a2761 100644 --- a/README.md +++ b/README.md @@ -4,11 +4,16 @@ ![NPM Downloads](https://img.shields.io/npm/dw/@freemius/checkout) [![Twitter](https://img.shields.io/twitter/follow/freemius.svg?style=social&label=@freemius)](https://twitter.com/freemius) -## Todos - -- [ ] Adjust the main export from `FSCheckout` to `Checkout`. -- [ ] Use the new `timestamp` and `sandbox_token` for testing with Sandbox. -- [ ] Create and publish the backward compatible adaptor. +- [Usage Guide](#usage-guide) + - [Using hosted CDN](#using-hosted-cdn) + - [Using NPM Package](#using-npm-package) +- [API](#api) + - [Instantiate the class](#instantiate-the-class) + - [Calling the method](#calling-the-method) +- [Use with React](#use-with-react) +- [Testing with Sandbox](#testing-with-sandbox) +- [Migration guide from the old checkout JS](#migration-guide-from-the-old-checkout-js) +- [Contributing](#contributing) ## Usage Guide @@ -277,7 +282,6 @@ export function useFSCheckout() { useEffect(() => { // close and destroy the DOM related stuff on unmount return () => { - fsCheckout.close(); fsCheckout.destroy(); }; }, [fsCheckout]); @@ -317,29 +321,6 @@ export default function App() { } ``` -## Setup Local Development Environment - -To work on the repository itself, please do the followings: - -1. Make sure you have latest Node.js LTS installed. -2. Clone the repository. -3. Copy `.env.sample` to `.env.local` and enter plugin id and public key as - specified in the file. - -Now run the following commands: - -```bash -# install dependencies -npm ci -# Run the development server -npm run dev -``` - -and it should spin up the server. Make sure to change the ID of plans in the -`.env.local` file. See -[vite documentation](https://vitejs.dev/guide/env-and-mode.html#env-files) to -learn about how `.env` files are handled. - ## Testing with Sandbox To get the sandbox token and ctx, follow the steps: @@ -419,3 +400,8 @@ recommend using the new API directly. The compatibility layer is only for quick migration. With the singleton pattern, every time you call the `configure` the original option will be overridden. While managing multiple checkouts, this can lead to confusion. + +## Contributing + +We welcome contributions! Please see the +[contribution guide](./CONTRIBUTING.md). diff --git a/cypress/support/commands.ts b/cypress/support/commands.ts index 698b01a..95857ae 100644 --- a/cypress/support/commands.ts +++ b/cypress/support/commands.ts @@ -34,4 +34,4 @@ // visit(originalFn: CommandOriginalFn, url: string, options: Partial): Chainable // } // } -// } \ No newline at end of file +// } diff --git a/cypress/support/e2e.ts b/cypress/support/e2e.ts index f80f74f..598ab5f 100644 --- a/cypress/support/e2e.ts +++ b/cypress/support/e2e.ts @@ -14,7 +14,7 @@ // *********************************************************** // Import commands.js using ES2015 syntax: -import './commands' +import './commands'; // Alternatively you can use CommonJS syntax: -// require('./commands') \ No newline at end of file +// require('./commands') diff --git a/package.json b/package.json index b5294b2..7b70b13 100644 --- a/package.json +++ b/package.json @@ -15,7 +15,9 @@ "deploysite": "npm run build && netlify deploy --dir=dist --prod", "prepublish": "npm run build:lib", "test": "jest", - "prepare": "ts-patch install -s" + "prepare": "ts-patch install -s", + "prettier:check": "prettier --check ./src ./tests ./cypress", + "prettier:write": "prettier --write ./src ./tests ./cypress" }, "devDependencies": { "@eslint/js": "^9.9.1", diff --git a/prettier.config.js b/prettier.config.js index 3985d4c..f1450aa 100644 --- a/prettier.config.js +++ b/prettier.config.js @@ -6,12 +6,11 @@ */ export default { - useTabs: false, - tabWidth: 4, - semi: true, - singleQuote: true, - trailingComma: 'es5', - bracketSpacing: true, - jsxBracketSameLine: false, - proseWrap: 'always', + useTabs: false, + tabWidth: 4, + semi: true, + singleQuote: true, + trailingComma: 'es5', + bracketSpacing: true, + proseWrap: 'always', };