From 9ff22e1826fcd4fd0fdf69f5a3e293e68399c16f Mon Sep 17 00:00:00 2001 From: Fabian Gruen Date: Wed, 6 Dec 2023 16:06:39 +0100 Subject: [PATCH 01/13] docs: add more detailed information about importance of the readme file --- docs/release/trg-1/trg-1-1.md | 37 ++++++++++++++++++++++++++--------- 1 file changed, 28 insertions(+), 9 deletions(-) diff --git a/docs/release/trg-1/trg-1-1.md b/docs/release/trg-1/trg-1-1.md index 7cd39d4b556..8af6b52aaf6 100644 --- a/docs/release/trg-1/trg-1-1.md +++ b/docs/release/trg-1/trg-1-1.md @@ -2,21 +2,40 @@ title: TRG 1.01 - README.md --- -| Status | Created | Post-History | -|--------|--------------|--------------| -| Active | 07-Mar-2023 | | -| Draft | 13-Sept-2022 | | +| Status | Created | Post-History | +|--------|--------------|------------------------------------------| +| Active | 06-Dec-2023 | add detailed information for README file | +| Active | 07-Mar-2023 | | +| Draft | 13-Sept-2022 | | ## Why -A good `README.md` file is the starting point for everyone opening a repository. It should help them find all critical information in an easy way. +A good `README.md` file is the starting point for everyone opening your repository. It should help them find all critical information in an easy way. +A well-maintained README reflects positively on the overall professionalism of the project. It shows that the developers care about user experience and want to make it easy for others to understand and use their work. ## Description Each repository **must** contain a `README.md` file which **shall** cover following topics: -- Basic description of repository and its content -- Installation instructions to get component working -- If required, additional post installation configuration steps to finish installation +- Basic documentation of repository and its content to understanding how your repository is structured and what it contains +- Setup and Installation Instructions to get your component working +- Configuration and Customization if required for additional post installation steps to finish installation +- Usage Examples and Demonstrations of you product +- License Information +- Troubleshooting and FAQs to help users solve common problems +- Contribution Guidelines to help users contribute to your project +- Contact Information to help users get in touch with you +- Professionalism and Credibility for your project +- Badges to show the status of your project (e.g. build status, code coverage, [etc](https://github.com/badges/shields/blob/master/README.md).) -If installation instructions are too comprehensive for `README.md` move content to `INSTALL.md` file, see [TRG 1.2](trg-1-2.md). +For our open-source eclipse tractus-x project, the `README.md` often includes guidelines on how others can contribute. This may cover aspects like submitting bug reports, suggesting new features, or providing code contributions. Clear contribution guidelines can help streamline collaboration. + +Common questions that are answered in the `README.md` file include: + +If installation instructions for your product are too comprehensive for `README.md` move content to `INSTALL.md` file, see [TRG 1.02](trg-1-2.md). +If your project is too complex to be described in a single `README.md` file, consider creating a `docs` folder and adding a `README.md` file there. This will help you keep your main repository directory clean and tidy. +If your project has multiple component repositories, link the other repositories in your leading repository in your `README.md` against to it. + +In summary, a good README is a crucial component of any repository, serving as a gateway for users and contributors to understand, use, and potentially contribute to your project. It's a fundamental part of effective project communication and collaboration. + +Further [example ideas](https://www.makeareadme.com/) how to create your `README.md` file. From f606a4c21c791e0a6615e7c1fab7f0feec2dd855 Mon Sep 17 00:00:00 2001 From: Fabian Gruen Date: Wed, 6 Dec 2023 16:30:35 +0100 Subject: [PATCH 02/13] docs: modify lowercase's --- docs/release/trg-1/trg-1-1.md | 12 ++++++------ 1 file changed, 6 insertions(+), 6 deletions(-) diff --git a/docs/release/trg-1/trg-1-1.md b/docs/release/trg-1/trg-1-1.md index 8af6b52aaf6..9162fc4a53e 100644 --- a/docs/release/trg-1/trg-1-1.md +++ b/docs/release/trg-1/trg-1-1.md @@ -18,14 +18,14 @@ A well-maintained README reflects positively on the overall professionalism of t Each repository **must** contain a `README.md` file which **shall** cover following topics: - Basic documentation of repository and its content to understanding how your repository is structured and what it contains -- Setup and Installation Instructions to get your component working -- Configuration and Customization if required for additional post installation steps to finish installation -- Usage Examples and Demonstrations of you product +- Setup and installation instructions to get your component working +- Configuration and customization if required for additional post installation steps to finish installation +- Usage examples and demonstrations of you product - License Information - Troubleshooting and FAQs to help users solve common problems -- Contribution Guidelines to help users contribute to your project -- Contact Information to help users get in touch with you -- Professionalism and Credibility for your project +- Contribution guidelines to help users contribute to your project +- Contact information to help users get in touch with you +- Professionalism and credibility for your project - Badges to show the status of your project (e.g. build status, code coverage, [etc](https://github.com/badges/shields/blob/master/README.md).) For our open-source eclipse tractus-x project, the `README.md` often includes guidelines on how others can contribute. This may cover aspects like submitting bug reports, suggesting new features, or providing code contributions. Clear contribution guidelines can help streamline collaboration. From c8d6f5a41f7bec98a9fb18c3e744e2653f90729d Mon Sep 17 00:00:00 2001 From: Fabian Gruen Date: Wed, 6 Dec 2023 16:34:51 +0100 Subject: [PATCH 03/13] docs: remove credibility --- docs/release/trg-1/trg-1-1.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/release/trg-1/trg-1-1.md b/docs/release/trg-1/trg-1-1.md index 9162fc4a53e..dc400fbd5ac 100644 --- a/docs/release/trg-1/trg-1-1.md +++ b/docs/release/trg-1/trg-1-1.md @@ -25,7 +25,7 @@ Each repository **must** contain a `README.md` file which **shall** cover follow - Troubleshooting and FAQs to help users solve common problems - Contribution guidelines to help users contribute to your project - Contact information to help users get in touch with you -- Professionalism and credibility for your project +- Professionalism and integrity for your project - Badges to show the status of your project (e.g. build status, code coverage, [etc](https://github.com/badges/shields/blob/master/README.md).) For our open-source eclipse tractus-x project, the `README.md` often includes guidelines on how others can contribute. This may cover aspects like submitting bug reports, suggesting new features, or providing code contributions. Clear contribution guidelines can help streamline collaboration. From 9496d1b037cf33e8b4eef355f7dd5d9e7d9d6e74 Mon Sep 17 00:00:00 2001 From: Fabian Gruen Date: Wed, 6 Dec 2023 16:36:55 +0100 Subject: [PATCH 04/13] docs: rewrite contribution reference --- docs/release/trg-1/trg-1-1.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/release/trg-1/trg-1-1.md b/docs/release/trg-1/trg-1-1.md index dc400fbd5ac..9f288e0dbc2 100644 --- a/docs/release/trg-1/trg-1-1.md +++ b/docs/release/trg-1/trg-1-1.md @@ -23,7 +23,7 @@ Each repository **must** contain a `README.md` file which **shall** cover follow - Usage examples and demonstrations of you product - License Information - Troubleshooting and FAQs to help users solve common problems -- Contribution guidelines to help users contribute to your project +- Contribution guidelines reference to your `CONTRIBUTING.md` file - Contact information to help users get in touch with you - Professionalism and integrity for your project - Badges to show the status of your project (e.g. build status, code coverage, [etc](https://github.com/badges/shields/blob/master/README.md).) From 1683f173282dd23ca0e8363292d3ab83c4f311b3 Mon Sep 17 00:00:00 2001 From: Fabian Gruen Date: Wed, 6 Dec 2023 16:41:19 +0100 Subject: [PATCH 05/13] docs: rewrite usage examples --- docs/release/trg-1/trg-1-1.md | 10 ++++------ 1 file changed, 4 insertions(+), 6 deletions(-) diff --git a/docs/release/trg-1/trg-1-1.md b/docs/release/trg-1/trg-1-1.md index 9f288e0dbc2..93864d5884c 100644 --- a/docs/release/trg-1/trg-1-1.md +++ b/docs/release/trg-1/trg-1-1.md @@ -20,7 +20,7 @@ Each repository **must** contain a `README.md` file which **shall** cover follow - Basic documentation of repository and its content to understanding how your repository is structured and what it contains - Setup and installation instructions to get your component working - Configuration and customization if required for additional post installation steps to finish installation -- Usage examples and demonstrations of you product +- Usage examples and intended use cases - License Information - Troubleshooting and FAQs to help users solve common problems - Contribution guidelines reference to your `CONTRIBUTING.md` file @@ -28,13 +28,11 @@ Each repository **must** contain a `README.md` file which **shall** cover follow - Professionalism and integrity for your project - Badges to show the status of your project (e.g. build status, code coverage, [etc](https://github.com/badges/shields/blob/master/README.md).) -For our open-source eclipse tractus-x project, the `README.md` often includes guidelines on how others can contribute. This may cover aspects like submitting bug reports, suggesting new features, or providing code contributions. Clear contribution guidelines can help streamline collaboration. - Common questions that are answered in the `README.md` file include: -If installation instructions for your product are too comprehensive for `README.md` move content to `INSTALL.md` file, see [TRG 1.02](trg-1-2.md). -If your project is too complex to be described in a single `README.md` file, consider creating a `docs` folder and adding a `README.md` file there. This will help you keep your main repository directory clean and tidy. -If your project has multiple component repositories, link the other repositories in your leading repository in your `README.md` against to it. +- If installation instructions for your product are too comprehensive for `README.md` move content to `INSTALL.md` file, see [TRG 1.02](trg-1-2.md). +- If your project is too complex to be described in a single `README.md` file, consider creating a `docs` folder and adding a `README.md` file there. This will help you keep your main repository directory clean and tidy. +- If your project has multiple component repositories, link the other repositories in your leading repository in your `README.md` against to it. In summary, a good README is a crucial component of any repository, serving as a gateway for users and contributors to understand, use, and potentially contribute to your project. It's a fundamental part of effective project communication and collaboration. From 069389e6f7e68565ed7d9198d26f336fda805312 Mon Sep 17 00:00:00 2001 From: Fabian Gruen Date: Wed, 6 Dec 2023 16:45:49 +0100 Subject: [PATCH 06/13] chore: update DEPENDENCIES file --- DEPENDENCIES | 3 +-- 1 file changed, 1 insertion(+), 2 deletions(-) diff --git a/DEPENDENCIES b/DEPENDENCIES index 57fd61577bc..cd2c20fa6ae 100644 --- a/DEPENDENCIES +++ b/DEPENDENCIES @@ -606,7 +606,7 @@ npm/npmjs/-/on-headers/1.0.2, MIT, approved, clearlydefined npm/npmjs/-/once/1.4.0, ISC, approved, clearlydefined npm/npmjs/-/onetime/5.1.2, MIT, approved, clearlydefined npm/npmjs/-/open/8.4.0, MIT, approved, #7102 -npm/npmjs/-/opener/1.5.2, MIT OR WTFPL OR (MIT AND WTFPL), approved, clearlydefined +npm/npmjs/-/opener/1.5.2, MIT AND WTFPL AND WTFPL, approved, #11619 npm/npmjs/-/p-cancelable/1.1.0, MIT, approved, clearlydefined npm/npmjs/-/p-limit/2.3.0, MIT, approved, clearlydefined npm/npmjs/-/p-limit/3.1.0, MIT, approved, clearlydefined @@ -728,7 +728,6 @@ npm/npmjs/-/react-json-view/1.21.3, MIT, approved, clearlydefined npm/npmjs/-/react-lifecycles-compat/3.0.4, MIT, approved, clearlydefined npm/npmjs/-/react-live/3.1.1, MIT, approved, clearlydefined npm/npmjs/-/react-loadable-ssr-addon-v5-slorber/1.0.1, MIT, approved, clearlydefined -npm/npmjs/-/react-loadable/5.5.2, MIT, approved, #6650 npm/npmjs/-/react-magic-dropzone/1.0.1, MIT, approved, #6622 npm/npmjs/-/react-markdown/8.0.5, MIT, approved, #6635 npm/npmjs/-/react-modal/3.16.1, MIT, approved, clearlydefined From 24f215a6b3abe992e7d5f3bea4a17fb828434042 Mon Sep 17 00:00:00 2001 From: Fabian Gruen Date: Wed, 6 Dec 2023 16:48:15 +0100 Subject: [PATCH 07/13] docs: rewrite contribution reference --- docs/release/trg-1/trg-1-1.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/release/trg-1/trg-1-1.md b/docs/release/trg-1/trg-1-1.md index 93864d5884c..8d42a2d7fd2 100644 --- a/docs/release/trg-1/trg-1-1.md +++ b/docs/release/trg-1/trg-1-1.md @@ -23,7 +23,7 @@ Each repository **must** contain a `README.md` file which **shall** cover follow - Usage examples and intended use cases - License Information - Troubleshooting and FAQs to help users solve common problems -- Contribution guidelines reference to your `CONTRIBUTING.md` file +- Reference your `CONTRIBUTING.md` file as Contribution guidelines to your project - Contact information to help users get in touch with you - Professionalism and integrity for your project - Badges to show the status of your project (e.g. build status, code coverage, [etc](https://github.com/badges/shields/blob/master/README.md).) From 9ccd6fdd7426d7b2f5ecb5d37697c336a063493c Mon Sep 17 00:00:00 2001 From: Fabian Gruen Date: Wed, 6 Dec 2023 16:52:03 +0100 Subject: [PATCH 08/13] docs: modify leading repo reference for readme + splitting the readme within docs folder --- docs/release/trg-1/trg-1-1.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/docs/release/trg-1/trg-1-1.md b/docs/release/trg-1/trg-1-1.md index 8d42a2d7fd2..b1794552563 100644 --- a/docs/release/trg-1/trg-1-1.md +++ b/docs/release/trg-1/trg-1-1.md @@ -31,8 +31,8 @@ Each repository **must** contain a `README.md` file which **shall** cover follow Common questions that are answered in the `README.md` file include: - If installation instructions for your product are too comprehensive for `README.md` move content to `INSTALL.md` file, see [TRG 1.02](trg-1-2.md). -- If your project is too complex to be described in a single `README.md` file, consider creating a `docs` folder and adding a `README.md` file there. This will help you keep your main repository directory clean and tidy. -- If your project has multiple component repositories, link the other repositories in your leading repository in your `README.md` against to it. +- If your project is too complex to be described in a single `README.md` file, consider creating a `docs` folder and add additional parts to your documentation. +- If your project has multiple component repositories, link the other repositories in your leading repository in your `README.md` towards each other. In summary, a good README is a crucial component of any repository, serving as a gateway for users and contributors to understand, use, and potentially contribute to your project. It's a fundamental part of effective project communication and collaboration. From 409037992f6ff3f7f93eb27e04e78edef5840b00 Mon Sep 17 00:00:00 2001 From: Fabian Gruen Date: Wed, 6 Dec 2023 17:07:17 +0100 Subject: [PATCH 09/13] docs: implement proposals --- docs/release/trg-1/trg-1-1.md | 18 +++++++++--------- 1 file changed, 9 insertions(+), 9 deletions(-) diff --git a/docs/release/trg-1/trg-1-1.md b/docs/release/trg-1/trg-1-1.md index b1794552563..08b1ad97d39 100644 --- a/docs/release/trg-1/trg-1-1.md +++ b/docs/release/trg-1/trg-1-1.md @@ -4,23 +4,23 @@ title: TRG 1.01 - README.md | Status | Created | Post-History | |--------|--------------|------------------------------------------| -| Active | 06-Dec-2023 | add detailed information for README file | +| Update | 06-Dec-2023 | add detailed information for README file | | Active | 07-Mar-2023 | | | Draft | 13-Sept-2022 | | ## Why A good `README.md` file is the starting point for everyone opening your repository. It should help them find all critical information in an easy way. -A well-maintained README reflects positively on the overall professionalism of the project. It shows that the developers care about user experience and want to make it easy for others to understand and use their work. +A well-maintained `README.md` shows high level of professionalism of the project. It shows that the developers care about user experience and want to make it easy for others to understand and use their work. ## Description Each repository **must** contain a `README.md` file which **shall** cover following topics: -- Basic documentation of repository and its content to understanding how your repository is structured and what it contains -- Setup and installation instructions to get your component working +- Basic documentation of the repository, its content and its structure +- Setup and installation instructions - Configuration and customization if required for additional post installation steps to finish installation -- Usage examples and intended use cases +- Usage examples and intended use of your product - License Information - Troubleshooting and FAQs to help users solve common problems - Reference your `CONTRIBUTING.md` file as Contribution guidelines to your project @@ -30,10 +30,10 @@ Each repository **must** contain a `README.md` file which **shall** cover follow Common questions that are answered in the `README.md` file include: -- If installation instructions for your product are too comprehensive for `README.md` move content to `INSTALL.md` file, see [TRG 1.02](trg-1-2.md). -- If your project is too complex to be described in a single `README.md` file, consider creating a `docs` folder and add additional parts to your documentation. -- If your project has multiple component repositories, link the other repositories in your leading repository in your `README.md` towards each other. +- If installation instructions for your product are too complex for `README.md` move content to `INSTALL.md` file, see [TRG 1.02](trg-1-2.md). +- If your project is too complex to be described in a single `README.md` file, consider creating a `docs` folder and add additional parts to your documentation and reference it. +- If your project has multiple component repositories, link the other repositories in your leading repository in your `README.md` mutually. In summary, a good README is a crucial component of any repository, serving as a gateway for users and contributors to understand, use, and potentially contribute to your project. It's a fundamental part of effective project communication and collaboration. -Further [example ideas](https://www.makeareadme.com/) how to create your `README.md` file. +Further [example](https://www.makeareadme.com/) on how to create your `README.md` file. From 50c7c79a224e3e18d19177da02970bbff7a83216 Mon Sep 17 00:00:00 2001 From: Fabian Gruen Date: Wed, 6 Dec 2023 17:13:09 +0100 Subject: [PATCH 10/13] docs: licence information --- docs/release/trg-1/trg-1-1.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/release/trg-1/trg-1-1.md b/docs/release/trg-1/trg-1-1.md index 08b1ad97d39..1cde0582aab 100644 --- a/docs/release/trg-1/trg-1-1.md +++ b/docs/release/trg-1/trg-1-1.md @@ -21,7 +21,7 @@ Each repository **must** contain a `README.md` file which **shall** cover follow - Setup and installation instructions - Configuration and customization if required for additional post installation steps to finish installation - Usage examples and intended use of your product -- License Information +- License information - Troubleshooting and FAQs to help users solve common problems - Reference your `CONTRIBUTING.md` file as Contribution guidelines to your project - Contact information to help users get in touch with you From c66d474541b2e65f050355d642c3d03ab3b358dc Mon Sep 17 00:00:00 2001 From: Fabian Gruen Date: Wed, 6 Dec 2023 17:15:13 +0100 Subject: [PATCH 11/13] docs: modify common answers --- docs/release/trg-1/trg-1-1.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/release/trg-1/trg-1-1.md b/docs/release/trg-1/trg-1-1.md index 1cde0582aab..a2488046b46 100644 --- a/docs/release/trg-1/trg-1-1.md +++ b/docs/release/trg-1/trg-1-1.md @@ -28,7 +28,7 @@ Each repository **must** contain a `README.md` file which **shall** cover follow - Professionalism and integrity for your project - Badges to show the status of your project (e.g. build status, code coverage, [etc](https://github.com/badges/shields/blob/master/README.md).) -Common questions that are answered in the `README.md` file include: +Best practices: - If installation instructions for your product are too complex for `README.md` move content to `INSTALL.md` file, see [TRG 1.02](trg-1-2.md). - If your project is too complex to be described in a single `README.md` file, consider creating a `docs` folder and add additional parts to your documentation and reference it. From de0ab53f160be64897c707e77fc25a2983c6437f Mon Sep 17 00:00:00 2001 From: Fabian Gruen Date: Tue, 12 Dec 2023 15:56:38 +0100 Subject: [PATCH 12/13] docs: optimize wording --- docs/release/trg-1/trg-1-1.md | 17 ++++++++--------- 1 file changed, 8 insertions(+), 9 deletions(-) diff --git a/docs/release/trg-1/trg-1-1.md b/docs/release/trg-1/trg-1-1.md index a2488046b46..5865afc02a8 100644 --- a/docs/release/trg-1/trg-1-1.md +++ b/docs/release/trg-1/trg-1-1.md @@ -11,28 +11,27 @@ title: TRG 1.01 - README.md ## Why A good `README.md` file is the starting point for everyone opening your repository. It should help them find all critical information in an easy way. -A well-maintained `README.md` shows high level of professionalism of the project. It shows that the developers care about user experience and want to make it easy for others to understand and use their work. +A well-maintained `README.md` shows the high level of professionalism of the project. It demonstrates that the developers care about user experience and want to make it easy for others to understand and use their work. ## Description Each repository **must** contain a `README.md` file which **shall** cover following topics: - Basic documentation of the repository, its content and its structure -- Setup and installation instructions -- Configuration and customization if required for additional post installation steps to finish installation +- Installation instructions + - If required necessary step(s) to finish the installation - Usage examples and intended use of your product - License information - Troubleshooting and FAQs to help users solve common problems -- Reference your `CONTRIBUTING.md` file as Contribution guidelines to your project -- Contact information to help users get in touch with you -- Professionalism and integrity for your project +- Reference your Contribution guideline in the `CONTRIBUTING.md` file +- Contact information to help users getting in touch with you - Badges to show the status of your project (e.g. build status, code coverage, [etc](https://github.com/badges/shields/blob/master/README.md).) Best practices: -- If installation instructions for your product are too complex for `README.md` move content to `INSTALL.md` file, see [TRG 1.02](trg-1-2.md). -- If your project is too complex to be described in a single `README.md` file, consider creating a `docs` folder and add additional parts to your documentation and reference it. -- If your project has multiple component repositories, link the other repositories in your leading repository in your `README.md` mutually. +- If installation instructions for your product are too complex being part of `README.md` move its content to a separate `INSTALL.md` file, see [TRG 1.02](trg-1-2.md). +- If your project is too complex to be described in a single `README.md` file, consider creating a `docs` folder and link your `README.md` to it. +- If your project has multiple component repositories (e.g. frontend and backend), link the other repositories in your leading repository in your `README.md` mutually. In summary, a good README is a crucial component of any repository, serving as a gateway for users and contributors to understand, use, and potentially contribute to your project. It's a fundamental part of effective project communication and collaboration. From cde008647f7011db8e47929d62c096456082e57a Mon Sep 17 00:00:00 2001 From: Fabian Gruen Date: Mon, 18 Dec 2023 13:30:46 +0100 Subject: [PATCH 13/13] docs: rephrase docs folder for readme --- docs/release/trg-1/trg-1-1.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/release/trg-1/trg-1-1.md b/docs/release/trg-1/trg-1-1.md index 5865afc02a8..8327657fbd8 100644 --- a/docs/release/trg-1/trg-1-1.md +++ b/docs/release/trg-1/trg-1-1.md @@ -30,7 +30,7 @@ Each repository **must** contain a `README.md` file which **shall** cover follow Best practices: - If installation instructions for your product are too complex being part of `README.md` move its content to a separate `INSTALL.md` file, see [TRG 1.02](trg-1-2.md). -- If your project is too complex to be described in a single `README.md` file, consider creating a `docs` folder and link your `README.md` to it. +- If your project is too complex to be described in a single `README.md` file, it may be beneficial to relocate specific sections to a dedicated `docs/` folder. - If your project has multiple component repositories (e.g. frontend and backend), link the other repositories in your leading repository in your `README.md` mutually. In summary, a good README is a crucial component of any repository, serving as a gateway for users and contributors to understand, use, and potentially contribute to your project. It's a fundamental part of effective project communication and collaboration.