From 2cf2f4678940847063d4dc083154298c5b98a321 Mon Sep 17 00:00:00 2001 From: Joshua Levy Date: Wed, 6 Jan 2016 21:47:15 -0800 Subject: [PATCH 1/7] Add contribution guidelines. --- CONTRIBUTING.md | 47 +++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 47 insertions(+) create mode 100644 CONTRIBUTING.md diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md new file mode 100644 index 0000000..f7a45ef --- /dev/null +++ b/CONTRIBUTING.md @@ -0,0 +1,47 @@ +## Contributing to The Art of Command Line + +This guide is a [collaborative effort](AUTHORS.md), based on the generous work of dozens contributors. + +Contributions of all kinds, including corrections, additions, improvements, and translations, are welcome! + +We hope you'll join and help, in small ways or large. +Here are few notes before you jump in. + +### Style + +- Stay close to the existing style of the document when possible. +- Remember to focus on brevity, specificity, and utility. +- Avoid long explanations and instead prefer links to resources. + +### Using issues and PRs + +- Please *create and comment on issues freely* to discuss. A lot of the difficulty in accepting PRs is around style and format, and whether changes should be made at all, so rationale or explanations for the change are useful. +- Please *review open issues and pull requests* before submitting a new one, to help reduce duplication. +- To the extent possible, *break up changes into multiple PRs* so they can be approved separately. Large contributions are also welcome, but are harder and slower to approve, as they tend to require discussion or rewriting. + +## Translations + +Maintaining the guide in several languages is a little confusing, so here is the process: + +- This original version and content of the guide is maintained in English. It has been translated to several other languages +- Each translation has a maintainer to update the translation as the original evolves and to review others' changes. This doesn't require a lot of time, but review by the maintainer is important to maintain quality. +- See the [AUTHORS.md](AUTHORS.md) file for current maintainers. (This file is generated from the [authors-info.yml](admin/authors-info.yml) file.) + +Changes to translations: + +- Changes to content should be made to the English version first, and then translated to each other language. +- Changes that improve translations should be made directly on the file for that language. PRs should only modify one language at a time. +- Submit a PR with changes to the file in that language. Each language has a maintainer, who reviews changes in that language. Then the primary maintainer @jlevy merges it in. +- Prefix PRs and issues with language codes if they are for that translation only, e.g. "es: Improve grammar", so maintainers can find them easily. + +Adding translations to new languages: + +- Translations to new languages are always welcome, especially if you can maintain the translation! +- If there is not an issue for your language, file one so people know you are working on it and we can arrange. Confirm you are native level in the language and are willing to maintain the translation, so it's not orphaned. +- If the translation is in progress but stalled, offer to help. +- To get it started, fork the repo, then submit a PR with the single file README-xx.md added, where xx is the lowercase language code. (Use standard two-letter ISO language codes, i.e. the same as is used by Wikipedia, not the code for a single country.) +- Invite friends to review if possible. If desired, feel free to invite friends to help your original translation by letting them fork your repo, then merging their PRs. +- When done, indicate on the PR that it's ready to be merged into the main repo. + +Further questions on process or want to volunteer to help in some other way? +File an issue or e-mail the original author @jlevy. From 4638c8b95edafb25f527ac8418d2b4d9a722f130 Mon Sep 17 00:00:00 2001 From: francescomalatesta Date: Thu, 7 Jan 2016 09:27:19 +0100 Subject: [PATCH 2/7] Adding some headers for separate sections (existing and new translations) --- CONTRIBUTING.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index f7a45ef..60e4ff3 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -27,14 +27,14 @@ Maintaining the guide in several languages is a little confusing, so here is the - Each translation has a maintainer to update the translation as the original evolves and to review others' changes. This doesn't require a lot of time, but review by the maintainer is important to maintain quality. - See the [AUTHORS.md](AUTHORS.md) file for current maintainers. (This file is generated from the [authors-info.yml](admin/authors-info.yml) file.) -Changes to translations: +### Changes to translations - Changes to content should be made to the English version first, and then translated to each other language. - Changes that improve translations should be made directly on the file for that language. PRs should only modify one language at a time. - Submit a PR with changes to the file in that language. Each language has a maintainer, who reviews changes in that language. Then the primary maintainer @jlevy merges it in. - Prefix PRs and issues with language codes if they are for that translation only, e.g. "es: Improve grammar", so maintainers can find them easily. -Adding translations to new languages: +### Adding translations to new languages - Translations to new languages are always welcome, especially if you can maintain the translation! - If there is not an issue for your language, file one so people know you are working on it and we can arrange. Confirm you are native level in the language and are willing to maintain the translation, so it's not orphaned. From fc022b584a3d32abd09e7897c2b89ef207905bc5 Mon Sep 17 00:00:00 2001 From: francescomalatesta Date: Thu, 7 Jan 2016 09:28:14 +0100 Subject: [PATCH 3/7] Making the first item in the new translations section a simple message --- CONTRIBUTING.md | 3 ++- 1 file changed, 2 insertions(+), 1 deletion(-) diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index 60e4ff3..e897de4 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -36,7 +36,8 @@ Maintaining the guide in several languages is a little confusing, so here is the ### Adding translations to new languages -- Translations to new languages are always welcome, especially if you can maintain the translation! +Translations to new languages are always welcome, especially if you can maintain the translation! + - If there is not an issue for your language, file one so people know you are working on it and we can arrange. Confirm you are native level in the language and are willing to maintain the translation, so it's not orphaned. - If the translation is in progress but stalled, offer to help. - To get it started, fork the repo, then submit a PR with the single file README-xx.md added, where xx is the lowercase language code. (Use standard two-letter ISO language codes, i.e. the same as is used by Wikipedia, not the code for a single country.) From 8d48e44ce3bdb32e19a3f7df96e26d96b589bf17 Mon Sep 17 00:00:00 2001 From: francescomalatesta Date: Thu, 7 Jan 2016 09:28:47 +0100 Subject: [PATCH 4/7] Moving up the getting started item in the new translations setction --- CONTRIBUTING.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index e897de4..3cf9ae0 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -38,9 +38,9 @@ Maintaining the guide in several languages is a little confusing, so here is the Translations to new languages are always welcome, especially if you can maintain the translation! +- To get it started, fork the repo, then submit a PR with the single file README-xx.md added, where xx is the lowercase language code. (Use standard two-letter ISO language codes, i.e. the same as is used by Wikipedia, not the code for a single country.) - If there is not an issue for your language, file one so people know you are working on it and we can arrange. Confirm you are native level in the language and are willing to maintain the translation, so it's not orphaned. - If the translation is in progress but stalled, offer to help. -- To get it started, fork the repo, then submit a PR with the single file README-xx.md added, where xx is the lowercase language code. (Use standard two-letter ISO language codes, i.e. the same as is used by Wikipedia, not the code for a single country.) - Invite friends to review if possible. If desired, feel free to invite friends to help your original translation by letting them fork your repo, then merging their PRs. - When done, indicate on the PR that it's ready to be merged into the main repo. From 5dbe213e3ed814feda53520119466a17a2eeea79 Mon Sep 17 00:00:00 2001 From: francescomalatesta Date: Thu, 7 Jan 2016 09:30:01 +0100 Subject: [PATCH 5/7] Added bold format to the main concepts of the entire document --- CONTRIBUTING.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index 3cf9ae0..8b8b27c 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -10,7 +10,7 @@ Here are few notes before you jump in. ### Style - Stay close to the existing style of the document when possible. -- Remember to focus on brevity, specificity, and utility. +- Remember to focus on **brevity**, **specificity**, and **utility**. - Avoid long explanations and instead prefer links to resources. ### Using issues and PRs From d2f2652dd6aaea058892974ca6f7938f31ba20e1 Mon Sep 17 00:00:00 2001 From: Joshua Levy Date: Thu, 7 Jan 2016 07:42:47 -0800 Subject: [PATCH 6/7] Tweaks to contributing guidelines. --- CONTRIBUTING.md | 10 +++++----- 1 file changed, 5 insertions(+), 5 deletions(-) diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index 8b8b27c..ad118a8 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -15,9 +15,9 @@ Here are few notes before you jump in. ### Using issues and PRs -- Please *create and comment on issues freely* to discuss. A lot of the difficulty in accepting PRs is around style and format, and whether changes should be made at all, so rationale or explanations for the change are useful. -- Please *review open issues and pull requests* before submitting a new one, to help reduce duplication. -- To the extent possible, *break up changes into multiple PRs* so they can be approved separately. Large contributions are also welcome, but are harder and slower to approve, as they tend to require discussion or rewriting. +- Please **create and comment on issues freely** to discuss. A lot of the difficulty in accepting PRs is around style and format, and whether changes should be made at all, so rationale or explanations for the change are useful. +- Please **review open issues and pull requests** before submitting a new one, to help reduce duplication. +- To the extent possible, **break up changes into multiple PRs** so they can be approved separately. Large contributions are also welcome, but are harder and slower to approve, as they tend to require discussion or rewriting. ## Translations @@ -38,9 +38,9 @@ Maintaining the guide in several languages is a little confusing, so here is the Translations to new languages are always welcome, especially if you can maintain the translation! +- Check existing issues to see if a translation is in progress or stalled. If so, offer to help. +- If it is not in progress, file an issue for your language so people know you are working on it and we can arrange. Confirm you are native level in the language and are willing to maintain the translation, so it's not orphaned. - To get it started, fork the repo, then submit a PR with the single file README-xx.md added, where xx is the lowercase language code. (Use standard two-letter ISO language codes, i.e. the same as is used by Wikipedia, not the code for a single country.) -- If there is not an issue for your language, file one so people know you are working on it and we can arrange. Confirm you are native level in the language and are willing to maintain the translation, so it's not orphaned. -- If the translation is in progress but stalled, offer to help. - Invite friends to review if possible. If desired, feel free to invite friends to help your original translation by letting them fork your repo, then merging their PRs. - When done, indicate on the PR that it's ready to be merged into the main repo. From bb347d41ff9029a888bff6a440b13dc8fe288a53 Mon Sep 17 00:00:00 2001 From: Joshua Levy Date: Thu, 7 Jan 2016 16:24:18 -0800 Subject: [PATCH 7/7] More tweaks to contributing guidelines. --- CONTRIBUTING.md | 10 +++++++--- 1 file changed, 7 insertions(+), 3 deletions(-) diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index ad118a8..2746cb1 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -1,6 +1,6 @@ ## Contributing to The Art of Command Line -This guide is a [collaborative effort](AUTHORS.md), based on the generous work of dozens contributors. +This guide is a [collaborative effort](AUTHORS.md), based on the generous work of many contributors. Contributions of all kinds, including corrections, additions, improvements, and translations, are welcome! @@ -19,6 +19,7 @@ Here are few notes before you jump in. - Please **review open issues and pull requests** before submitting a new one, to help reduce duplication. - To the extent possible, **break up changes into multiple PRs** so they can be approved separately. Large contributions are also welcome, but are harder and slower to approve, as they tend to require discussion or rewriting. + ## Translations Maintaining the guide in several languages is a little confusing, so here is the process: @@ -44,5 +45,8 @@ Translations to new languages are always welcome, especially if you can maintain - Invite friends to review if possible. If desired, feel free to invite friends to help your original translation by letting them fork your repo, then merging their PRs. - When done, indicate on the PR that it's ready to be merged into the main repo. -Further questions on process or want to volunteer to help in some other way? -File an issue or e-mail the original author @jlevy. +### Further questions + +Unsure of the process? +Or do you have skills and inclination to help in a more substantial way? +File an issue or e-mail the original author [@jlevy](https://github.com/jlevy).