From 2b32b4e804f42d300d69d3c560b015904eaae62a Mon Sep 17 00:00:00 2001 From: Dariksha Date: Tue, 18 Jun 2024 12:12:42 +0530 Subject: [PATCH 1/5] Added reference documentation policy Signed-off-by: Dariksha --- CONTRIBUTING.md | 19 ++++++++++++++++++- 1 file changed, 18 insertions(+), 1 deletion(-) diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index df2a876..5604ea9 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -37,4 +37,21 @@ The specifics of development practices for a sub-project or implementation are detailed in their repositories. For implementations, this includes information such as the name of the development branch and any additional checks pertaining to that project. For ITEs, the process of submitting a new proposal is described -in ITE-1. \ No newline at end of file +in ITE-1. + +## Reference Documentation Policy + +For any new implementation, reference documentation should be included in the implementation repository on GitHub. Specifically, the sources and generation information should be located in a `doc` subdirectory within the implementation repository. + +To ensure comprehensive documentation, refer to the [Python Reference Implementation's reference docs](https://github.com/in-toto/in-toto/tree/develop/doc) as a guideline for the necessary details. These reference docs are generated using source files and a makefile located in the implementation's `doc` subdirectory. + +#### Example Structure +``` +implementation-repo/ +├── doc/ +│ ├── source/ +│ ├── Makefile +│ └── ... +└── src/ +└── ... +``` \ No newline at end of file From f897a9c49979812e01616c960bf7f50a95ed5afe Mon Sep 17 00:00:00 2001 From: Dariksha Date: Tue, 18 Jun 2024 12:52:25 +0530 Subject: [PATCH 2/5] Changed reference documentation policy Signed-off-by: Dariksha --- CONTRIBUTING.md | 11 ----------- 1 file changed, 11 deletions(-) diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index 5604ea9..9c87f8f 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -44,14 +44,3 @@ in ITE-1. For any new implementation, reference documentation should be included in the implementation repository on GitHub. Specifically, the sources and generation information should be located in a `doc` subdirectory within the implementation repository. To ensure comprehensive documentation, refer to the [Python Reference Implementation's reference docs](https://github.com/in-toto/in-toto/tree/develop/doc) as a guideline for the necessary details. These reference docs are generated using source files and a makefile located in the implementation's `doc` subdirectory. - -#### Example Structure -``` -implementation-repo/ -├── doc/ -│ ├── source/ -│ ├── Makefile -│ └── ... -└── src/ -└── ... -``` \ No newline at end of file From ee96e60ea9ece6211b3a8c80509475d312d38a5f Mon Sep 17 00:00:00 2001 From: Dariksha Date: Tue, 18 Jun 2024 12:56:30 +0530 Subject: [PATCH 3/5] resolved all the requested changes Signed-off-by: Dariksha --- CONTRIBUTING.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index 9c87f8f..d16c9e7 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -41,6 +41,6 @@ in ITE-1. ## Reference Documentation Policy -For any new implementation, reference documentation should be included in the implementation repository on GitHub. Specifically, the sources and generation information should be located in a `doc` subdirectory within the implementation repository. +For any new implementation, reference documentation should be included in its repository on GitHub, following documentation best practices specific to the implementation language. -To ensure comprehensive documentation, refer to the [Python Reference Implementation's reference docs](https://github.com/in-toto/in-toto/tree/develop/doc) as a guideline for the necessary details. These reference docs are generated using source files and a makefile located in the implementation's `doc` subdirectory. +To ensure comprehensive documentation, refer to the [Python Reference Implementation's reference docs](http://in-toto.readthedocs.io) as a guideline. From 44d0f6f0525aa3bc8dd71d0e1364656beaebb3d3 Mon Sep 17 00:00:00 2001 From: Dariksha Date: Tue, 18 Jun 2024 13:23:32 +0530 Subject: [PATCH 4/5] Added Instructions for Editors Signed-off-by: Dariksha --- CONTRIBUTING.md | 39 ++++++++++++++++++++++++++++++++++++++- 1 file changed, 38 insertions(+), 1 deletion(-) diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index d16c9e7..3f1eacb 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -14,7 +14,7 @@ They are: corresponding GitHub repositories Any developer or user submitting these types of changes is considered an in-toto -contributor. Over time, as described in [in-toto's Governance](GOVERNANCE.md), +contributor. Over time, as described in [in-toto's Governance](GOVERNANCE.md), contributors may be promoted to maintainers of relevant implementations or sub-projects. @@ -44,3 +44,40 @@ in ITE-1. For any new implementation, reference documentation should be included in its repository on GitHub, following documentation best practices specific to the implementation language. To ensure comprehensive documentation, refer to the [Python Reference Implementation's reference docs](http://in-toto.readthedocs.io) as a guideline. + +### Instructions for Editors + +If you need to update the reference documentation, follow these steps: + +1. **Locate the Documentation Source:** + The source files for the reference documentation are found in the `doc/source` directory of the implementation repository. + +``` +implementation-repo/ +├── doc/ +│ ├── source/ +│ ├── Makefile +│ └── ... +└── src/ +└── ... +``` + +2. **Make Your Changes:** +Edit the necessary source files in the `doc/source` directory. Ensure your changes comply with the project's documentation standards. + +3. **Build the Documentation:** +Use the provided `Makefile` in the `doc` directory to generate the updated documentation. Typically, you can run: + +```sh +make html +``` + +4. **Submit a Pull Request:** +Submit a pull request with your changes. Your PR should include: + +* A description of the changes made. +* Any relevant issue numbers. +* A link to the contribution policy. + +5. **Review and Approval:** +Changes to the reference documentation are reviewed by the maintainers. Ensure you follow the project's contribution guidelines for a smooth review process. From e7a7a340a1a66d3d96e2dc89a5bab87b44477713 Mon Sep 17 00:00:00 2001 From: Dariksha Date: Tue, 18 Jun 2024 15:18:44 +0530 Subject: [PATCH 5/5] reverted the last changes Signed-off-by: Dariksha --- CONTRIBUTING.md | 39 +-------------------------------------- 1 file changed, 1 insertion(+), 38 deletions(-) diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index 3f1eacb..d16c9e7 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -14,7 +14,7 @@ They are: corresponding GitHub repositories Any developer or user submitting these types of changes is considered an in-toto -contributor. Over time, as described in [in-toto's Governance](GOVERNANCE.md), +contributor. Over time, as described in [in-toto's Governance](GOVERNANCE.md), contributors may be promoted to maintainers of relevant implementations or sub-projects. @@ -44,40 +44,3 @@ in ITE-1. For any new implementation, reference documentation should be included in its repository on GitHub, following documentation best practices specific to the implementation language. To ensure comprehensive documentation, refer to the [Python Reference Implementation's reference docs](http://in-toto.readthedocs.io) as a guideline. - -### Instructions for Editors - -If you need to update the reference documentation, follow these steps: - -1. **Locate the Documentation Source:** - The source files for the reference documentation are found in the `doc/source` directory of the implementation repository. - -``` -implementation-repo/ -├── doc/ -│ ├── source/ -│ ├── Makefile -│ └── ... -└── src/ -└── ... -``` - -2. **Make Your Changes:** -Edit the necessary source files in the `doc/source` directory. Ensure your changes comply with the project's documentation standards. - -3. **Build the Documentation:** -Use the provided `Makefile` in the `doc` directory to generate the updated documentation. Typically, you can run: - -```sh -make html -``` - -4. **Submit a Pull Request:** -Submit a pull request with your changes. Your PR should include: - -* A description of the changes made. -* Any relevant issue numbers. -* A link to the contribution policy. - -5. **Review and Approval:** -Changes to the reference documentation are reviewed by the maintainers. Ensure you follow the project's contribution guidelines for a smooth review process.