From 35bc56c77f3ba8a58cf88d00ded7cd7fbf20a1a2 Mon Sep 17 00:00:00 2001 From: xDivisionByZerox Date: Sun, 3 Dec 2023 12:20:29 +0100 Subject: [PATCH 01/10] wip: add contributing pages --- docs/contributing/code-of-conduct.md | 7 +++++++ docs/contributing/propose-a-feature.md | 7 +++++++ docs/contributing/report-a-bug.md | 12 ++++++++++++ docs/contributing/run-the-tests.md | 0 .../contributing/set-up-a-development-environment.md | 0 docs/contributing/submit-a-pull-request.md | 0 6 files changed, 26 insertions(+) create mode 100644 docs/contributing/code-of-conduct.md create mode 100644 docs/contributing/propose-a-feature.md create mode 100644 docs/contributing/report-a-bug.md create mode 100644 docs/contributing/run-the-tests.md create mode 100644 docs/contributing/set-up-a-development-environment.md create mode 100644 docs/contributing/submit-a-pull-request.md diff --git a/docs/contributing/code-of-conduct.md b/docs/contributing/code-of-conduct.md new file mode 100644 index 00000000000..a648f93a1cc --- /dev/null +++ b/docs/contributing/code-of-conduct.md @@ -0,0 +1,7 @@ +--- +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/propose-a-feature.md b/docs/contributing/propose-a-feature.md new file mode 100644 index 00000000000..43409cb8012 --- /dev/null +++ b/docs/contributing/propose-a-feature.md @@ -0,0 +1,7 @@ +# Propose a Feature + +## Propose a New Method + +## Propose a New Module + +## Propose a New Locale diff --git a/docs/contributing/report-a-bug.md b/docs/contributing/report-a-bug.md new file mode 100644 index 00000000000..6017fedc977 --- /dev/null +++ b/docs/contributing/report-a-bug.md @@ -0,0 +1,12 @@ +# Report Bugs + +If you think you’ve found a bug in Faker, please create a new issue or a pull request on GitHub. + +Please include as much detail as possible to help us properly address your issue. +If we need to triage issues and constantly ask people for more detail, that’s time taken away from actually fixing issues. +Help us be as efficient as possible by including a lot of detail in your issues. +To make this process as easy as possible for you, please make sure to use the "Bug" issue template in GitHub. + +::: info Note +If you just have a question that won’t necessarily result in a change to Faker, such as asking how something works or how to contribute, please open a [discussion](https://github.com/faker-js/faker/discussions) or stop by our Discord server instead of filing an issue. +::: diff --git a/docs/contributing/run-the-tests.md b/docs/contributing/run-the-tests.md new file mode 100644 index 00000000000..e69de29bb2d 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 00000000000..e69de29bb2d diff --git a/docs/contributing/submit-a-pull-request.md b/docs/contributing/submit-a-pull-request.md new file mode 100644 index 00000000000..e69de29bb2d From f2e75f96cbe8a5fa545efaf4cd055e6b4f76f1cd Mon Sep 17 00:00:00 2001 From: xDivisionByZerox Date: Sat, 27 Apr 2024 13:34:51 +0200 Subject: [PATCH 02/10] refactor: remove run-the-tests page --- docs/contributing/run-the-tests.md | 0 1 file changed, 0 insertions(+), 0 deletions(-) delete mode 100644 docs/contributing/run-the-tests.md diff --git a/docs/contributing/run-the-tests.md b/docs/contributing/run-the-tests.md deleted file mode 100644 index e69de29bb2d..00000000000 From 7adb68259840d4467e4a577451db0025f48dcc07 Mon Sep 17 00:00:00 2001 From: xDivisionByZerox Date: Sat, 27 Apr 2024 13:35:38 +0200 Subject: [PATCH 03/10] refactor: rename report bugs page file --- docs/contributing/{report-a-bug.md => report-bugs.md} | 0 1 file changed, 0 insertions(+), 0 deletions(-) rename docs/contributing/{report-a-bug.md => report-bugs.md} (100%) diff --git a/docs/contributing/report-a-bug.md b/docs/contributing/report-bugs.md similarity index 100% rename from docs/contributing/report-a-bug.md rename to docs/contributing/report-bugs.md From 7bb00dd17e10ca58a4f47413c494afb0bdcdb264 Mon Sep 17 00:00:00 2001 From: xDivisionByZerox Date: Sat, 27 Apr 2024 20:54:30 +0200 Subject: [PATCH 04/10] docs: add contributing sidebar entry --- docs/.vitepress/config.ts | 60 +++++++++++++++++++++++++++++++++------ 1 file changed, 52 insertions(+), 8 deletions(-) diff --git a/docs/.vitepress/config.ts b/docs/.vitepress/config.ts index e92efc8e073..2ed63da36d4 100644 --- a/docs/.vitepress/config.ts +++ b/docs/.vitepress/config.ts @@ -34,6 +34,31 @@ function extendSideNav(current: SidebarItem): SidebarItem[] { }, ], }, + { + 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: [ @@ -49,10 +74,6 @@ function extendSideNav(current: SidebarItem): SidebarItem[] { text: 'Team', link: '/about/team', }, - { - text: 'Contributing', - link: '/about/contributing', - }, ], }, ]; @@ -175,10 +196,6 @@ const config: UserConfig = { text: 'Team', link: '/about/team', }, - { - text: 'Contributing', - link: '/about/contributing', - }, ], }, { @@ -230,11 +247,38 @@ const config: UserConfig = { }, ], }), + '/api/': extendSideNav({ text: 'API', items: apiPages, }), + '/contributing/': extendSideNav({ + 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', + }, + ], + }), + '/about/': extendSideNav({ text: 'About', items: [ From 13f2b8fb13b3bcca80b1c393a29eefc7908e1511 Mon Sep 17 00:00:00 2001 From: xDivisionByZerox Date: Sat, 27 Apr 2024 20:54:55 +0200 Subject: [PATCH 05/10] docs: remove contributing page under about --- docs/about/contributing.md | 7 ------- 1 file changed, 7 deletions(-) delete mode 100644 docs/about/contributing.md diff --git a/docs/about/contributing.md b/docs/about/contributing.md deleted file mode 100644 index a648f93a1cc..00000000000 --- 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) From ff806e102d7c2dc13e46ffa58b63d1c85d3a4cdf Mon Sep 17 00:00:00 2001 From: xDivisionByZerox Date: Sat, 27 Apr 2024 22:43:20 +0200 Subject: [PATCH 06/10] docs: update "code-of-conduct" page --- docs/contributing/code-of-conduct.md | 6 ++++-- 1 file changed, 4 insertions(+), 2 deletions(-) diff --git a/docs/contributing/code-of-conduct.md b/docs/contributing/code-of-conduct.md index a648f93a1cc..bd5b1c5a4d4 100644 --- a/docs/contributing/code-of-conduct.md +++ b/docs/contributing/code-of-conduct.md @@ -2,6 +2,8 @@ editLink: false --- -# Contributing +# Code of Conduct -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) +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). From f820b7e04cd865c1ca5a9ea984567cd8ece57110 Mon Sep 17 00:00:00 2001 From: xDivisionByZerox Date: Sat, 27 Apr 2024 23:02:08 +0200 Subject: [PATCH 07/10] docs: update "report-bugs" page --- docs/contributing/report-bugs.md | 10 +++++----- 1 file changed, 5 insertions(+), 5 deletions(-) diff --git a/docs/contributing/report-bugs.md b/docs/contributing/report-bugs.md index 6017fedc977..07a43a1fb14 100644 --- a/docs/contributing/report-bugs.md +++ b/docs/contributing/report-bugs.md @@ -1,12 +1,12 @@ # Report Bugs -If you think you’ve found a bug in Faker, please create a new issue or a pull request on GitHub. +If you think you’ve found a bug in Faker, please create 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 allows you to provide steps to reproduce, and allows other users to confirm this is actually a bug. Please include as much detail as possible to help us properly address your issue. -If we need to triage issues and constantly ask people for more detail, that’s time taken away from actually fixing issues. -Help us be as efficient as possible by including a lot of detail in your issues. -To make this process as easy as possible for you, please make sure to use the "Bug" issue template in GitHub. +By including comprehensive information upfront, you assist us in efficiently addressing your concerns. +This approach minimizes the need for follow-up questions and allows us to focus on resolving the issue promptly. ::: info Note -If you just have a question that won’t necessarily result in a change to Faker, such as asking how something works or how to contribute, please open a [discussion](https://github.com/faker-js/faker/discussions) or stop by our Discord server instead of filing an issue. +If you just have a question that won’t necessarily result in a change to Faker, such as asking how something works or how to contribute, please open a [discussion](https://github.com/faker-js/faker/discussions) or stop by our [Discord server](https://chat.fakerjs.dev) instead of filing an issue. ::: From bf37530945071c7c6a5394e5f6cf2c42bd9e572e Mon Sep 17 00:00:00 2001 From: xDivisionByZerox Date: Wed, 1 May 2024 20:34:54 +0200 Subject: [PATCH 08/10] docs: update "propose a feature" page --- docs/contributing/propose-a-feature.md | 50 ++++++++++++++++++++++++-- 1 file changed, 47 insertions(+), 3 deletions(-) diff --git a/docs/contributing/propose-a-feature.md b/docs/contributing/propose-a-feature.md index 43409cb8012..67d209ad32e 100644 --- a/docs/contributing/propose-a-feature.md +++ b/docs/contributing/propose-a-feature.md @@ -1,7 +1,51 @@ # Propose a Feature -## Propose a New Method +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). -## Propose a New Module +`@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. -## Propose a New Locale +## General Feature Guideline + +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 Fakers 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 rule 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 additionally requirements. + +::: tip Note +Using thumb-up emotes ( :+1: ) on issues gives the faker team a general idea of the community interest in a feature. +If you see a feature request that you like, leave an up vote to increase interest. +You can obviously also up vote you own feature requests. +::: + +### New Locale Criteria + +Faker already contains [over 60 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 systematic way. +Ideally you use this name in the issues 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. +Hopefully, these can be outsourced to the person requesting the feature or another person from 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). From b740f3c6fdbcb25f167571f69ede70654bd4dde7 Mon Sep 17 00:00:00 2001 From: DivisionByZero Date: Thu, 2 May 2024 00:39:32 +0200 Subject: [PATCH 09/10] chore: apply suggestions from code review Co-authored-by: ST-DDT --- docs/.vitepress/config.ts | 8 ++++---- docs/contributing/propose-a-feature.md | 5 ++--- 2 files changed, 6 insertions(+), 7 deletions(-) diff --git a/docs/.vitepress/config.ts b/docs/.vitepress/config.ts index 91671d8502e..9f78e0c983d 100644 --- a/docs/.vitepress/config.ts +++ b/docs/.vitepress/config.ts @@ -61,19 +61,19 @@ function getSideBarWithExpandedEntry(entryToExpand: string): SidebarItem[] { link: '/contributing/code-of-conduct', }, { - text: 'Report Bugs', + text: 'Reporting Bugs', link: '/contributing/report-bugs', }, { - text: 'Propose a Feature', + text: 'Proposing a Feature', link: '/contributing/propose-a-feature', }, { - text: 'Set up a Development Environment', + text: 'Setting up a Development Environment', link: '/contributing/set-up-a-development-environment', }, { - text: 'Submit a Pull Request', + text: 'Submiting a Pull Request', link: '/contributing/submit-a-pull-request', }, ], diff --git a/docs/contributing/propose-a-feature.md b/docs/contributing/propose-a-feature.md index 67d209ad32e..1ec0fa41dd0 100644 --- a/docs/contributing/propose-a-feature.md +++ b/docs/contributing/propose-a-feature.md @@ -18,7 +18,7 @@ General criteria for new features are as follows: ## Accepting a Feature -In order for a rule to be accepted in Faker, it must fulfill all the criteria listed in [General Feature Guideline](#general-feature-guideline). +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 additionally requirements. ::: tip Note @@ -33,7 +33,7 @@ Faker already contains [over 60 different locales](/guide/localization#available 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 systematic way. -Ideally you use this name in the issues title and description. +Ideally, you use this name in the issues title and description. ## Considerations @@ -41,7 +41,6 @@ Our goal is to maintain the library efficiently, ensuring that new features are 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. -Hopefully, these can be outsourced to the person requesting the feature or another person from 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. From bad0b2980292eda0d8695bba92cbda43735911a6 Mon Sep 17 00:00:00 2001 From: DivisionByZero Date: Sun, 14 Jul 2024 15:05:41 +0200 Subject: [PATCH 10/10] docs: apply suggestions from code review Co-authored-by: Eric Cheng --- docs/.vitepress/config.ts | 2 +- docs/contributing/propose-a-feature.md | 10 +++++----- 2 files changed, 6 insertions(+), 6 deletions(-) diff --git a/docs/.vitepress/config.ts b/docs/.vitepress/config.ts index ddcccdcf5ef..ddc63c5ddfa 100644 --- a/docs/.vitepress/config.ts +++ b/docs/.vitepress/config.ts @@ -73,7 +73,7 @@ function getSideBarWithExpandedEntry(entryToExpand: string): SidebarItem[] { link: '/contributing/set-up-a-development-environment', }, { - text: 'Submiting a Pull Request', + text: 'Submitting a Pull Request', link: '/contributing/submit-a-pull-request', }, ], diff --git a/docs/contributing/propose-a-feature.md b/docs/contributing/propose-a-feature.md index 1ec0fa41dd0..a85bbe0522e 100644 --- a/docs/contributing/propose-a-feature.md +++ b/docs/contributing/propose-a-feature.md @@ -19,12 +19,12 @@ General criteria for new features are as follows: ## 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 additionally requirements. +Additionally, depending on the type of feature, there might be additional requirements. ::: tip Note -Using thumb-up emotes ( :+1: ) on issues gives the faker team a general idea of the community interest in a feature. +Using thumb-up emotes ( :+1: ) on issues gives the Faker team a general idea of the community interest in a feature. If you see a feature request that you like, leave an up vote to increase interest. -You can obviously also up vote you own feature requests. +You can obviously also upvote your own feature requests. ::: ### New Locale Criteria @@ -32,8 +32,8 @@ You can obviously also up vote you own feature requests. Faker already contains [over 60 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 systematic way. -Ideally, you use this name in the issues title and description. +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