These contribution instructions MUST be used when the following are all true:
The ToIP Deliverable is an instance of one of the following types:
- Recommendation - Design Principle
- Recommendation - Best Practice
The contributors have decided to collaborate on a single markdown file as their authoring approach.
Our trustoverip/deliverables GitHub repo is used to maintain certain types of recommendations. We use standard GitHub activities to track issues and feature requests, as well as accept all Pull Requests (
PR's) related to the deliverables managed in this repo.
As a member contributor, use the
trustoverip/deliverables repository to contribute to the ToIP Foundation in easy and transparent manner, whether it's:
- Reporting a bug
- Discussing the current state of the ToIP Deliverable
- Submitting a fix
- Proposing process recommendations
General GitHub Workflow¶
- Issue Submission / Tracking
- Pull requests
- Organization Resources
- General GitHub Resources
Before proposing a new deliverable, consider the following preparatory actions:
- Exploring the idea in the appropriate WG Slack Channel.
- Socialize the idea during a WG meeting.
- Make use of the mailing lists to socialize the idea and to make an assessment that your proposal is novel and you will not be overlapping work already proposed.
- Make use of the Deliverables Portal for a current listing of all work product efforts and their statuses so that you can appropriately position your proposal as unique.
- Make a decision as to the type of deliverable you will be proposing.
- Discuss the roles each contributor will perform. Some members may be knowledgable content contributors, some may be skilled in GitHub, other may have both skills.
- Establish a preliminary outline for the content you will be delivering and who may be contributing specific sections of work.
Submit a Proposal¶
- Fork and clone the Deliverables Repo.
- In a terminal window, change directories to the
Pick a descriptive folder name for your new deliverable following our naming conventions. Don't pick a number yet.
[~/deliverables/recommendations] ==> mkdir BP0000-utility-selection-criteria [~/deliverables/recommendations] ==> cd BP0000-utility-selection-criteria [~/deliverables/recommendations/BP0000-utility-selection-criteria] ==>
- Decide on a clear and simple name that is descriptive, yet not verbose or vague.
- Create a new folder.
- Navigate into your new folder.
Copy the appropriate template from the
templatesfolder to your new folder. See Exploring Templates.
[~/deliverables/recommendations/BP0000-utility-selection-criteria] ==> cp ../../templates/Recommendations/Best_Practice_tmplt.md . [~/deliverables/recommendations/BP0000-utility-selection-criteria] ==> mv Best_Practice_tmplt.md BP0000-utility-selection-criteria.md
The template file provides an outline to guide your work. Use the outline to bootstrap your work on the deliverable. Use MUST and SHOULD per standard conventions. Put care into the details! Deliverable submissions that do not present sufficient information as suggested by the template tend to be poorly received. You can add supporting artifacts and organize your folder as desired. You MAY want to:
- Create an
imagesfolder to store
.pngfiles that your content may reference.
- Leverage PlantUML tools for the generation of UML diagrams. When doing so, you MUST include in your folder:
.pumlfiles in a
Leverage presentation tools (i.e.: PowerPoint, Keynote). When doing so, you MUST include in your folder:
/images /src /puml interaction_diagram.puml /presentations diagrams.key slides.ppt interaction_diagram.svg interaction_diagram.png interaction_diagram.jpg diagram_1.png slide_1.jpg
- Create an
Consider how your new proposal should be tagged.
When you are ready to submit the draft proposal you will need to obtain a unique deliverable identifier. To assign a number to your deliverable submission. Get the number by loading this web page.
- Rename your folder name using the new number
- Rename your file name to reflect the new number
At the top of your file modify the title so it is in the form:
<TypeIndicator><4digitID>: Friendly Version of Your Title.
Commit your changes.
- Commit an updated version of
../results/proposed.mdand push your changes.
- Submit a pull request.
- Make sure that all of your commits satisfy the DCO requirements of the repo and conform to the license restrictions noted below.
- The ToIP Deliverable Maintainers will check to see if the process has been followed, and request any process changes before merging the PR.
- When the PR is merged, your deliverable is now formally in the Proposed state.