diff options
Diffstat (limited to 'docs')
| -rw-r--r-- | docs/.vitepress/config.ts | 34 | ||||
| -rw-r--r-- | docs/about/contributing.md | 7 | ||||
| -rw-r--r-- | docs/contributing/code-of-conduct.md | 9 | ||||
| -rw-r--r-- | docs/contributing/propose-a-feature.md | 50 | ||||
| -rw-r--r-- | docs/contributing/report-bugs.md | 16 | ||||
| -rw-r--r-- | docs/contributing/set-up-a-development-environment.md | 62 | ||||
| -rw-r--r-- | docs/contributing/submit-a-pull-request.md | 215 |
7 files changed, 378 insertions, 15 deletions
diff --git a/docs/.vitepress/config.ts b/docs/.vitepress/config.ts index 6054ee41..73ed6270 100644 --- a/docs/.vitepress/config.ts +++ b/docs/.vitepress/config.ts @@ -63,6 +63,31 @@ function getSideBarWithExpandedEntry(entryToExpand: string): SidebarItem[] { items: apiPages, }, { + text: 'Contributing', + items: [ + { + text: 'Code of Conduct', + link: '/contributing/code-of-conduct', + }, + { + text: 'Report Bugs', + link: '/contributing/report-bugs', + }, + { + text: 'Propose a Feature', + link: '/contributing/propose-a-feature', + }, + { + text: 'Set up a Development Environment', + link: '/contributing/set-up-a-development-environment', + }, + { + text: 'Submit a Pull Request', + link: '/contributing/submit-a-pull-request', + }, + ], + }, + { text: 'About', items: [ { @@ -94,10 +119,6 @@ function getSideBarWithExpandedEntry(entryToExpand: string): SidebarItem[] { text: 'Team', link: '/about/team', }, - { - text: 'Contributing', - link: '/about/contributing', - }, ], }, ]; @@ -214,10 +235,6 @@ For a full list of all methods please refer to https://fakerjs.dev/api/\`, logSt text: 'Team', link: '/about/team', }, - { - text: 'Contributing', - link: '/about/contributing', - }, ], }, { @@ -238,6 +255,7 @@ For a full list of all methods please refer to https://fakerjs.dev/api/\`, logSt sidebar: { '/guide/': getSideBarWithExpandedEntry('Guide'), '/api/': getSideBarWithExpandedEntry('API'), + '/contributing/': getSideBarWithExpandedEntry('Contributing'), '/about/': getSideBarWithExpandedEntry('About'), }, }, diff --git a/docs/about/contributing.md b/docs/about/contributing.md deleted file mode 100644 index a648f93a..00000000 --- a/docs/about/contributing.md +++ /dev/null @@ -1,7 +0,0 @@ ---- -editLink: false ---- - -# Contributing - -We welcome new contributors! For more information see the [Contributing](https://github.com/faker-js/faker/blob/next/CONTRIBUTING.md) file on Github. All contributors are expected to follow the [Code of Conduct](https://github.com/faker-js/faker/blob/next/CODE_OF_CONDUCT.md) diff --git a/docs/contributing/code-of-conduct.md b/docs/contributing/code-of-conduct.md new file mode 100644 index 00000000..bd5b1c5a --- /dev/null +++ b/docs/contributing/code-of-conduct.md @@ -0,0 +1,9 @@ +--- +editLink: false +--- + +# Code of Conduct + +We welcome new contributors! +We appreciate your interest in making Faker a better library. +Please note that all contributors are expected to follow the [Code of Conduct](https://github.com/faker-js/faker/blob/next/CODE_OF_CONDUCT.md). diff --git a/docs/contributing/propose-a-feature.md b/docs/contributing/propose-a-feature.md new file mode 100644 index 00000000..cfb20197 --- /dev/null +++ b/docs/contributing/propose-a-feature.md @@ -0,0 +1,50 @@ +# Propose a Feature + +If you want to propose a new feature in Faker, please create a new issue using the [Feature Request Template](https://github.com/faker-js/faker/issues/new?labels=s%3A+pending+triage%2Cc%3A+feature%2Cs%3A+waiting+for+user+interest&projects=&template=feature_request.yml). + +`@faker-js/faker` is all about enhancing the developer experience with realistic fake data. +As our library grows, we welcome contributions that introduce new features and maintain the cohesive functionality of our existing codebase. +To ensure quality and consistency, we have established guidelines for contributing new features. + +## General Feature Guidelines + +General criteria for new features are as follows: + +- **Relevance**: Must be widely applicable and not specific to a particular niche. +- **Deterministic**: Functions must be based on Faker's internal [Randomizer](/api/randomizer). +- **Conflict-Free**: Should not conflict with or duplicate existing features. +- **Utility**: Provides significant value to a broad user base. +- **Library-Agnostic**: Implementations must be based solely on JavaScript runtime environments and not on specific libraries or frameworks. + +## Accepting a Feature + +In order for a feature to be accepted in Faker, it must fulfill all the criteria listed in [General Feature Guideline](#general-feature-guideline). +Additionally, depending on the type of feature, there might be additional requirements. + +::: tip Note +Using thumb-up emojis ( :+1: ) on issues helps the Faker estimate the community interest in a feature. +If you see a feature request that you like, leave an up vote to increase interest. +Feel free to upvote your own feature requests as well. +::: + +## Criteria for New Locales + +Faker already contains [over 70 different locales](/guide/localization#available-locales). + +If you want to propose a new locale that does not already exist, make sure to read our guide on [locale code names](/guide/localization#locale-codes). +You should be able to name your locale using the provided naming standards. +Ideally, you should also use this name in the issue's title and description. + +## Considerations + +Our goal is to maintain the library efficiently, ensuring that new features are indispensable. +Each addition to Faker comes with associated costs. +This encompasses initial expenses like design, implementation, review, and documentation of the feature. +Ideally, these tasks can be delegated to the requester or another member of the community. + +Moreover, ongoing maintenance of Faker incurs further costs, including awareness of the feature, a more intricate module structure, increased bundle size, and additional effort during refactoring. + +If your feature isn't accepted into the library, you can still create it using Faker's Helper methods. +Our goal is to empower developers, not limit possibilities. + +For more details on creating custom features, refer to our documentation on [Create Complex Objects](/guide/usage#create-complex-objects). diff --git a/docs/contributing/report-bugs.md b/docs/contributing/report-bugs.md new file mode 100644 index 00000000..3f11ee12 --- /dev/null +++ b/docs/contributing/report-bugs.md @@ -0,0 +1,16 @@ +# Report Bugs + +Thank you for taking the time to help improve Faker! +Your contributions are invaluable in keeping the project reliable and useful for everyone. +We kindly ask that you follow the guidelines below when reporting a bug. +Providing clear and detailed information allows us to verify problems quickly and work toward effective solutions. + +If you believe you've discovered a bug in Faker, please submit a new issue using the [Bug Report Template](https://github.com/faker-js/faker/issues/new?labels=s%3A+pending+triage%2Cc%3A+bug&template=bug_report.yml). +This will help you provide clear reproduction steps and allow other users to verify that the issue is indeed a bug. + +To facilitate a swift resolution, please include as much relevant detail as possible. +Providing comprehensive information upfront reduces the need for follow-up questions, enabling us to focus on resolving the issue efficiently. + +::: info Note +If you have a general question that doesn't require a change to Faker - such as understanding how something works or learning how to contribute - please start a [discussion](https://github.com/faker-js/faker/discussions) or join our [Discord server](https://chat.fakerjs.dev) instead of opening an issue. +::: diff --git a/docs/contributing/set-up-a-development-environment.md b/docs/contributing/set-up-a-development-environment.md new file mode 100644 index 00000000..53b63c7d --- /dev/null +++ b/docs/contributing/set-up-a-development-environment.md @@ -0,0 +1,62 @@ +--- +outline: [2, 3] +--- + +# Set Up a Development Environment + +Setting up a local development environment for Faker allows you to contribute effectively to the project. +Whether you prefer working directly on your machine or using a containerized setup, the following steps will guide you through the process. + +## Step 1: Fork and Clone the Repository + +Before you begin, you need to fork the Faker repository and clone it to your local machine. + +::: tip Note +If you are unfamiliar with Forks, check out [GitHub Forking Guide](https://docs.github.com/en/get-started/quickstart/fork-a-repo). +::: + +1. Go to the [Faker GitHub repository](https://github.com/faker-js/faker) and click the **Fork** button. +1. Open a terminal and clone your fork: + ```sh + git clone https://github.com/<Your_GitHub_Username>/faker + ``` +1. Navigate into the cloned directory: + ```sh + cd faker + ``` +1. Add the upstream source to keep your fork updated: + ```sh + git remote add upstream https://github.com/faker-js/faker.git + ``` + +## Step 2: Choose Your Development Setup + +Faker can be developed using two different methods: + +- [On your machine](#option-1-native-nodejs-environment) +- [In a development container](#option-2-vscode-devcontainer-integration) + +### Option 1: Native Node.js Environment + +If you prefer working directly on your machine, follow these steps: + +1. Ensure you have [the current LTS version of Node.js](https://nodejs.org/en/download) installed. +1. Ensure you have the package manager [`pnpm`](https://pnpm.io/installation) installed. +1. Run the preflight command to verify your setup: + ```sh + pnpm run preflight + ``` + +### Option 2: VSCode Devcontainer Integration + +For a streamlined development experience, Faker supports VSCode Devcontainers. + +1. Open the Faker repository in VSCode. +1. Install the [Dev Containers extension](https://marketplace.visualstudio.com/items?itemName=ms-vscode-remote.remote-containers) if you haven't already. +1. Open the command palette (`Ctrl+Shift+P` or `Cmd+Shift+P` on macOS) and select "**Dev Containers: Reopen in Container**". +1. Wait for the container to build and start. + +## Step 3: Submit a Pull Request + +Your development environment has successfully been set up. +You are now ready to [Submit a Pull Request](./submit-a-pull-request.md). diff --git a/docs/contributing/submit-a-pull-request.md b/docs/contributing/submit-a-pull-request.md new file mode 100644 index 00000000..df8f4cdf --- /dev/null +++ b/docs/contributing/submit-a-pull-request.md @@ -0,0 +1,215 @@ +# Submit a Pull Request + +A lot of effort has been put into `Faker` to create a useful and handy library. +There are still a lot of things to be done! +If you want to make `Faker` a better place, please follow the steps below when submitting a pull request. + +## Step 1: Ensure Your Branch is Up-to-Date + +Before making changes, ensure your fork is synchronized with Faker’s latest updates: + +```sh +git fetch upstream +git merge upstream/next origin/next +``` + +## Step 2: Create a New Branch + +Create a new branch for your changes: + +```sh +git switch -c my-branch-name +``` + +Using descriptive branch names makes reviewing easier, but also helps you identify the reason for a branch if you contribute multiple PR to Faker. + +## Step 3: Make Your Changes + +Now, modify the necessary files, ensuring they align with Faker’s coding standards. +If your PR introduces new functionality, update documentation accordingly. + +## Step 4: Run Preflight Checks + +Before committing, verify your changes meet Faker’s quality standards: + +```sh +pnpm run preflight +``` + +The command is a useful all-in-one command provided by the Faker team, to make development as easy as possible. +It is a shorthand for running the following scripts in order: + +- `pnpm install` - installs npm packages defined in package.json +- `pnpm run generate:locales` - generates locale files +- `pnpm run generate:api-docs` - generates API documentation +- `pnpm run format` - runs [prettier](https://github.com/prettier/prettier) to format code +- `pnpm run lint` - runs [ESLint](https://github.com/eslint/eslint) to enforce project code standards +- `pnpm run build:clean` - removes artifacts from previous builds +- `pnpm run build:code` - builds the code, both CommonJS and ESM versions +- `pnpm run test:update-snapshots` - runs all tests with [vitest](https://github.com/vitest-dev/vitest), and updates any snapshots if needed +- `pnpm run ts-check` - checks that there are no TypeScript errors in any files + +::: tip Note +The `preflight` command is very helpful when switching between different branches, +to get your local environment synced up with the branch's state. +::: + +## Step 5: Commit and Push Your Changes + +Once everything looks good, commit your changes: + +```sh +git commit -m "feat: Add support for XYZ functionality" +git push origin my-branch-name +``` + +Faker does not enforce a specific commit convention. +Instead, all commits are squashed into a single commit when you PR is merged. +Writing meaningful commit messages might still be advantageous. +This way you get to reflect on the changes you have done and reviewers can get an easier, higher level understanding from your submission. + +## Step 6: Open a Pull Request + +Navigate to your forked repository on GitHub and open a pull request against Faker’s next branch. + +PR Guidelines: + +- Clearly explain your changes and why they are needed. +- Reference related issues when applicable. +- Keep your PR focused—avoid bundling multiple unrelated changes. +- If applicable, add tests to cover new functionality. + +### The Pull Request Title + +A Pull Request title needs to follow the semantic of a [conventional commit](https://www.conventionalcommits.org), since it is used as commit message when merging your PR. +These commit messages are then used to automatically update the [CHANGELOG](https://github.com/faker-js/faker/blob/next/CHANGELOG.md) file for each release version. + +PR titles are written in following convention: `type(scope): subject` + +**type** is required and indicates the intent of the PR. + +::: tip Note +The types `feat` and `fix` will be shown in the CHANGELOG as `### Features` or `### Bug Fixes`. +The type `refactor` will also show up as `### Changed Locales` if it has the `locale` scope. +All other types wont show up except for breaking changes marked with the `!` in front of `:` +::: + +Allowed types are: + +| type | description | Shows Up In CHANGELOG | +| -------- | ------------------------------------------------------------------------- | -------------------------------------------- | +| feat | A new feature is introduced | :white_check_mark: | +| fix | A bug was fixed | :white_check_mark: | +| chore | No user affected code changes were made | :x: | +| refactor | A refactoring that affected also user (e.g. log a deprecation warning) | :white_check_mark: (with the `locale` scope) | +| docs | Docs were added or changed | :x: | +| test | Test were added or changed | :x: | +| ci | CI were added or changed | :x: | +| build | Build scripts were added or changed | :x: | +| infra | Infrastructure related things were made (e.g. issue-template was updated) | :x: | +| revert | A revert was triggered via git | :x: | + +**scope** is optional and indicates the scope of the PR. + +::: tip Note +The scope will be shown in the changelog in front of the _subject_ in bold text. +Commits are sorted alphabetically. +This way, the scope will group commits indirectly into categories. +::: + +Allowed scopes are: + +| scope | description | +| --------------- | ---------------------------------------------------------------------------- | +| \<module-name\> | The specific module name that was affected by the PR | +| locale | When only locale(s) are added/updated/removed | +| module | When some modules where updates or something related to modules were changed | +| revert | When a revert was made via git | +| deps | Will mostly be used by Renovate | +| release | Will be set by release process | + +::: tip Note +The scope is not checkable via `Semantic Pull Request` action as this would limit the scopes to only existing modules, +but if we add a new module like `color`, then the PR author couldn't use the new module name as scope. +As such, we (the Faker team) must be mindful of valid scopes and we reserve the right to edit titles as we see fit. +::: + +**subject** is required and describes what the PR does. + +Please note that the PR title should not include a suffix of e.g. `(#123)`. +This will be done automatically by GitHub while merging. + +Some examples of valid pull request titles: + +```shell +feat: add casing option +feat(locale): extend Hebrew (he) +fix: lower target to support Webpack 4 +chore: add naming convention rule +refactor(location): deprecate streetPrefix and streetSuffix +docs: remove unused playground +test: validate @see contents +ci: allow breaking change commits +build: add node v18 support +infra: rework bug-report template +revert: add more arabic names dataset (#362) + +# Breaking changes +refactor!: remove faker default export +build!: remove node v12 support + +# A release PR will look like this +chore(release): 7.4.0 + +# Renovate automatically generates these +chore(deps): update devdependencies +chore(deps): update typescript-eslint to ~5.33.0 +``` + +Previous pull request titles that could have been written in a better way: + +```diff +- feat: `datatype.hexadecimal` signature change ++ feat(datatype): hexadecimal signature change + datatype was one of our modules and can be used as scope + +- feat(image): add image via.placeholder provider ++ feat(image): add via.placeholder provider + image was redundant in the subject + +- feat(system.networkInterface): add networkInterface faker ++ feat(system): add networkInterface method + networkInterface was redundant in the scope and made the whole commit message long + also method in the subject explains a bit better what it is + +- chore(bug-report-template): new design ++ infra: rework bug-report template + the type infra tells that no actual code-changes were made + the subject contains what the PR does + +- chore: rename Gender to Sex ++ refactor(name): rename Gender to Sex + this was not a chore as it touched runtime code that affected the end-user + scope name can be used here to tell that the change affects only the name module +``` + +## Step 7: Address Feedback and Iterate + +Faker maintainers may request modifications. +Be open to suggestions and update your PR as needed. + +::: info Note +The [Faker Team](/about/team) is made up of volunteers contributing in their free time. +Please understand if you Pull Request is not getting an immediate review. +::: + +## Step 8: Celebrate Your Contribution! 🎉 + +Your changes will generally be merged after: + +1. One member of the Faker team has approved your submission and no additional requests have been issued by another team member for 7 days. +1. Two members of the Faker team have approved your submission and no additional requests have been issued by another team member for 24 hours. +1. At least three members of the Faker team have approved your submission. + +Afterwards, your changes will be merged into Faker's codebase, helping thousands of developers! +Thank you for contributing. 🚀 |