From aed2ac125adf88c975ab8cd49461029ada18ad65 Mon Sep 17 00:00:00 2001 From: Scott Lee Date: Fri, 17 May 2024 17:23:25 +0900 Subject: [PATCH] Update contributing guide #2 (#707) --- CONTRIBUTING.md | 58 ++++++++++++++++++++++++-------- README.md | 44 +++++++++++++++++++++++- docs/learn/accounts.md | 2 +- docs/learn/learn.md | 4 +-- docs/{learn => misc}/glossary.md | 0 sidebars.js | 2 +- 6 files changed, 91 insertions(+), 19 deletions(-) rename docs/{learn => misc}/glossary.md (100%) diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index 9af1cb39890..3a6009d0add 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -7,19 +7,20 @@ Thank you for your interest in contributing to Klaytn Docs. As an open source pr 1. Read this [contributing document](./CONTRIBUTING.md). 2. Sign [Contributor Licensing Agreement (CLA)](#contributor-license-agreement-cla). 3. Submit an issue with a proper [labelling](#usage-of-labels). -4. Please wait until the label changes to `contribution welcome` - otherwise, it is not ready to be worked on. -5. Only after the label changed to `contribution welcome`, you can start submitting the changes. To avoid any duplicate efforts, it is recommended to update the issue so that other contributors could see someone working on the issue. -6. Before making a Pull Request (PR), please make sure the suggested content changes are accurate and linked with the corresponding issue reported. After submitting the PR, wait for code review and approval. The reviewer may ask you for additional commits or changes. -7. All PRs should be made against the `master` branch, and following the successful build, the suggested content change could be previewed with GitBook preview feature (clicking `Details` under `Show all checks`). -8. Once the change has been approved, the PR is merged by the project moderator. -9. After merging the PR, the pull request will be closed. You can then delete the now obsolete branch. -10. https://docs.klaytn.foundation/ will be updated with the suggested changes (merged content). +4. Wait for contribution approval: The project moderators will review your issue and update the label to `contribution welcome` if it's ready to be worked on. Please avoid duplicate efforts by checking the issue status before starting your contribution. +5. Start contributing: Once your issue is approved, you can start working on the changes. Update the issue to inform other contributors that you're actively working on it. +6. Make a Pull Request (PR): Ensure your proposed changes are accurate, well-documented, and linked to the corresponding issue. Submit a PR against the `main` branch and wait for code review and approval. +7. Address review feedback: The reviewer may request additional commits or changes. Be responsive and address their feedback to ensure your contribution aligns with the project's standards. +8. PR merge and branch deletion: Once approved, the project moderator will merge your PR into the main branch. You can then safely delete your working branch. +9. Content update: The Klaytn Docs website (https://docs.klaytn.foundation/) will be updated with your merged contribution. ## Types of Contribution + There are various ways to contribute and participate. Please read the guidelines below regarding the process of each type of contribution. -- [Issues and Typos](#issues-and-typos) -- [Content Contribution](#content-contribution) +- [Issues and Typos](#issues-and-typos) +- [Content Contribution](#content-contribution) +- [Content Translation](#content-translation) ### Issues and Typos @@ -28,7 +29,7 @@ If you could identify issues and typos in Klaytn docs, before submitting an issu - The issue is not a duplicate issue. - The issue has not been covered in the latest release of Klaytn Docs. - The issue covers minor typos or errors on the existing content of Klaytn Docs. -Please do not use the issue tracker for personal support requests. Use developer@klaytn.com for the personal support requests. +Please do not use the issue tracker for personal support requests. Use developers@klaytn.foundation for the personal support requests. After confirming your report meets the above criteria, [submit the issue](https://github.com/klaytn/klaytn-docs/issues). Please use [labels](#usage-of-labels) to specify your issue as `issues-and-typos`. @@ -39,11 +40,20 @@ If you would recommend major content change in Klaytn docs, before submitting an - The issue is not a duplicate issue. - The issue has not been covered in the latest release of Klaytn Docs. - The issue covers major content change (e.g. Adding/removing paragraph and chapter in Klaytn Docs, adding/removing graphical explanation, etc.) on the existing content of Klaytn Docs. -Please do not use the issue tracker for personal support requests. Use developer@klaytn.com for the personal support requests. +Please do not use the issue tracker for personal support requests. Use developers@klaytn.foundation for the personal support requests. After confirming your report meets the above criteria, [submit the issue](https://github.com/klaytn/klaytn-docs/issues). Please use [labels](#usage-of-labels) to specify your issue as `content-contribution`. -#### Usage of Labels +### Content Translation + +If you are fluent in a language other than English and want to contribute translations or improve the localized documentation, [submit an issue](https://github.com/klaytn/klaytn-docs/issues). Please use [labels](#usage-of-labels) to specify your issue as `content-translation`. + +You need to use the [Crowdin](https://crowdin.com/project/klaytn-docs) platform to contribute translations. For more information, see the [Internationalization](https://docs.klaytn.foundation/docs/misc/internationalization/) page. + +> [!IMPORTANT] +> For content translation, avoid using a pull request to submit changes by modifying the files under the [i18n](https://github.com/klaytn/klaytn-docs/tree/main/i18n) directory directly.

Unlike other types of contribution, the translations are managed by Crowdin localization management platform. If a translation is submitted and has been approved in Crowdin, an automated PR will be made to Klaytn docs repo. Once the PR is approved and merged by the project moderators, the localized Klaytn docs will be updated with the suggested changes (merged content). + +## Usage of Labels You can use the following labels: @@ -51,13 +61,14 @@ Labels for initial issue categories: - issue/issues-and-typos: Issues with the minor content typos and inaccuracy. - issue/content-contribution: Issues with major content contributions. +- issue/content-translation: Issues with content translations. Status of open issues (will be tagged by the project moderators): - (no label): The default status. - open/need more information : The issue's creator needs to provide additional information to review. - open/reviewing: The issue is under review. -- open/re-label needed: The label needs to be changed to confirmed as being a `issues-and-typos` or future `content-contribution`. +- open/re-label needed: The label needs to be changed to confirmed as being a `issues-and-typos`, future `content-contribution`, or `content-translation`. - open/contribution welcome: The content fix or update is approved and you are invited to contribute to it. Status of closed issues: @@ -67,8 +78,27 @@ Status of closed issues: - closed/invalid: The issue is not applicable to the Klaytn Docs. - closed/reject: The issue is rejected after review. +## Additional Contribution Guidelines + +Here are some additional guidelines to follow when contributing to Klaytn Docs: + +### Commit Messages + +- Start with a capitalized and imperative verb. Examples include "Update", "Fix", "Add", "Improve", etc. +- Use a consistent format for commit messages. A common pattern is "verb: description of change" (for example, "Update contract addresses for Kaia chain"). +- Keep the subject line short and descriptive. It should clearly communicate the scope and focus of the change. + +### Build and Dependencies + +If your contribution involves adding new code or dependencies, ensure the project continues to build successfully after your changes by running a build command (for example, `npm run build`). + +### Image Optimization + +- Keep all images optimized and compressed to minimize file size (under 30kb whenever possible). This helps to improve website loading speed and keeps the repository size manageable. +- Consider using tools like [Trimage](https://trimage.org/) to optimize your images. + ## Contributor License Agreement (CLA) Keep in mind when you submit your pull request, you'll need to sign the CLA via [CLA-Assistant](https://cla-assistant.io/klaytn/klaytn-docs) for legal purposes. You will have to sign the CLA just one time, either as an individual or corporation. -You will be prompted to sign the agreement by CLA Assistant (bot) when you open a Pull Request for the first time. +You will be also prompted to sign the agreement by CLA Assistant (bot) when you open a Pull Request for the first time. Post the comment "I have read the CLA Document and I hereby sign the CLA" in the PR. \ No newline at end of file diff --git a/README.md b/README.md index eeac193f355..6b7797f595e 100644 --- a/README.md +++ b/README.md @@ -1,6 +1,48 @@ +# Klaytn Docs + +Welcome to the Klaytn documentation repository! This repo contains the source files for the official Klaytn documentation available at https://docs.klaytn.foundation. + > [!IMPORTANT] > Attention content contributors! Klaytn docs has shifted platforms, migrating from Gitbook to **Docusaurus**. For key information about this transition and its impact on your contributions, please refer to [the Klaytn docs 2.0 announcement](https://klaytn.foundation/announcing-klaytn-docs-2-0-streamlined-searchable-and-community-powered/). +## Contributing + +We welcome contributions to help us improve and expand the Klaytn documentation. There are a few ways you can contribute: + +### Contributing to Documentation + +If you find issues in the docs or have suggestions for improvements, please open an issue or submit a pull request. See our [Contributing Guide](https://github.com/klaytn/klaytn-docs/blob/main/CONTRIBUTING.md) for more details on the contribution workflow. + +Before submitting PRs, make sure to: + +- Create an issue with an appropriate [label](https://github.com/klaytn/klaytn-docs/blob/main/CONTRIBUTING.md#usage-of-labels). +- Provide a clear and detailed description of the changes. +- Reference any related issues or pull requests. +- Ensure your changes render correctly and pass all tests. + +### Contributing Translations + +Klaytn docs is available in the following languages: + +- English +- 한국어 +- Tiếng Việt + +If you are fluent in a language other than English and want to contribute translations or improve the localized documentation, see the [Internationalization](https://docs.klaytn.foundation/docs/misc/internationalization/) page for details on how to contribute translations via Crowdin. + +Some key points: + +- Create an issue with the `content-translation` label. +- Join the translator team on the [Klaytn-Docs Crowdin project](https://crowdin.com/project/klaytn-docs). +- Select the language you want to contribute to. +- Choose the files to translate or vote on translations. +- Ensure your word choices conform to the Klaytn Terminologies. +- Be respectful and follow the translation Code of Conduct. + +Translation suggestions will be reviewed by the maintainers and made available on the localized doc sites when approved and merged. + +## Developing Klaytn Docs + This website is built using Docusaurus v3. ### Installation @@ -39,4 +81,4 @@ Not using SSH: $ GIT_USER= yarn deploy ``` -If you are using GitHub pages for hosting, this command is a convenient way to build the website and push to the `gh-pages` branch. +If you are using GitHub pages for hosting, this command is a convenient way to build the website and push to the `gh-pages` branch. \ No newline at end of file diff --git a/docs/learn/accounts.md b/docs/learn/accounts.md index aa25d9aae64..881087ae5db 100644 --- a/docs/learn/accounts.md +++ b/docs/learn/accounts.md @@ -44,7 +44,7 @@ This format is currently supported in [Klaytn Wallet](../build/tools/wallets/kla ### Klaytn Account Types -There are two types of accounts in Klaytn: externally owned accounts \(EOAs\), and smart contract accounts \(SCAs\). +There are two types of accounts in Klaytn: externally owned accounts \(EOAs\), and smart contract accounts \(SCAs\). #### Externally Owned Accounts \(EOAs\) diff --git a/docs/learn/learn.md b/docs/learn/learn.md index 31d307cb6db..5ab663d5e81 100644 --- a/docs/learn/learn.md +++ b/docs/learn/learn.md @@ -15,7 +15,7 @@ Klaytn launched its mainnet, [Cypress](https://klaytnscope.com), on Jun/27/2019 - 4,000 transactions per second. - Low gas price that is almost 1/10 of Ethereum. - Runs EVM (Ethereum Virtual Machine) and supports the execution of Solidity contracts. -- 19 reputable corporations worldwide initially formed Klaytn Governance Council to operate consensus nodes. The current number of consensus nodes is shown in the [Klaytnscope](https://klaytnscope.com). +- 19 reputable corporations worldwide initially formed Klaytn Governance Council to operate consensus nodes. The current number of consensus nodes is shown in the [Klaytnscope](https://klaytnscope.com). - More than 50 initial service partners have committed to launch Blockchain Applications on Klaytn. ## Klaytn: The Big Picture @@ -120,7 +120,7 @@ may be influenced by network traffic and node operation conditions. #### Proposer and Committee Selection In each round, Klaytn randomly but deterministically selects a Consensus Node -(CN) as the proposer for the block to be created, and then selects a group of CNs as the committee for the given round. Klaytn is not directly involved in +(CN) as the proposer for the block to be created, and then selects a group of CNs as the committee for the given round. Klaytn is not directly involved in the selection of either the proposer or committee; instead, each CN uses a random number derived from the most recent block header to run a cryptographic operation which yields proof that the CN has (or has not) been selected for diff --git a/docs/learn/glossary.md b/docs/misc/glossary.md similarity index 100% rename from docs/learn/glossary.md rename to docs/misc/glossary.md diff --git a/sidebars.js b/sidebars.js index 83ed411e8dc..c9eda4cd6e9 100644 --- a/sidebars.js +++ b/sidebars.js @@ -40,6 +40,7 @@ const commonSidebar = [ ], }, 'misc/klaytn-history', + 'misc/glossary', 'misc/faq', 'misc/opensource', 'misc/terms-of-use', @@ -111,7 +112,6 @@ const sidebars = { 'learn/klaytn2/metaverse-package', ], }, - 'learn/glossary', ...commonSidebar, ], buildSidebar: [