Skip to content

TianoCore Documents Editing

Jump to bottom
Michael Kinney edited this page Oct 28, 2022 · 5 revisions

The following is a summary of steps to edit a document. The steps listed here use the master branch from the document repository which is always the latest DRAFT version of the document. The same steps can be used to fix an issue in a release version of a document, but a release/version branch would be used instead of the master branch.

The steps described here uses three copies of a document. The official version of the document in a tianocore-docs project repository. This is the repository that the GitBook server watches for changes to trigger publication actions. The second copy is a fork of the document from the tianocore-docs project into a developer's personal GitHub area. This fork provides a place to share a public version of the document changes to support reviews. The third copy is on the developer's local system. This is the copy that is used to make local edits and review changes before sharing the changes on the edk2-devel mailing list and on the developer's personal GitHub area. Once all reviews are passed, the changes are pushed to tianocore-docs and a new DRAFT version of the document is published by the GitBook server. The TianoCore Wiki pages provide links to these DRAFT versions for all developers.

  1. TianoCore Bugzilla issue is entered against a document
  2. TianoCore Bugzilla issue is confirmed and assigned to developer
  3. Create a fork of the document repository in developer's own GitHub area
  4. Clone the fork of the document repository to local system
  5. Add remote to document in tianocore-docs document repository
  6. Checkout master branch
  7. If fork/clone/remote already present, then update master branch to latest
  8. Create a new local branch with branch name of Bugzilla_<ID>_<Title>
  9. Add link to Bugzilla issue along with title to Revision History in README.md
  10. Edit document source files to resolve the Bugzilla issue
  11. Do local builds of the document to review changes and formatting
  12. Run BaseTools/Scripts/PatchCheck.py to check commit contents.
  13. Commit changes to local branch with link to Bugzilla issue in commit message
  14. Push branch to developer's fork of the documents repository
    • GitBook project linked to developer's fork of the document can also be setup and used to review the changes and formatting before sending patch review email to the community.
  15. Send patch review email to edk2-devel.
    • Add link to branch in developer's fork to summary email
    • Add links to GitHub word difference view of each patch to summary email
  16. Discuss patches on edk2-devel until all issues resolved and Reviewed-by received.
  17. Update commit messages with Reviewed-by lines
  18. Sync with tianocore-docs document repository master branch
  19. Run BaseTools/Scripts/PatchCheck.py to check commit contents.
  20. Push change from developer branch to tianocore-docs repository master branch
  21. Update Bugzilla issue with link to GitHub commit and update state to Resolved/Fixed

Example editing Draft of EDK II Template Specification

The following shows some example GIT commands that follow the steps described above. GIT is very flexible, so there are many different ways to perform these steps. Items in example commands surrounded by <> need to be substituted.

  • Use a browser to open the EDK II Template Specification GitHub repository

    https://github.com/tianocore-docs/edk2-TemplateSpecification

  • Select Fork to create a fork of this repository and select your own user account to create fork.

  • Clone your personal fork of the EDK II Template Specification GitHub repository to your local system.

    git clone https://github.com/<user>/edk2-TemplateSpecification.git
cd edk2-TemplateSpecification

  • Add remote to EDK II Template Specification in tiancore-docs repository

    git remote add tianocore-docs https://github.com/tianocore-docs/edk2-TemplateSpecification.git

    After this command, there should be two remotes. The original one called origin that points to the personal fork and the new one called tianocore-docs. Changes pushed to origin will only change the contents of the personal fork. Changes pushed to tianocore-docs changes the contents of the official document and automatically trigger a publishing action on the GitBook server. Run the following command to verify the remotes are setup correctly.

    git remote -v

    The expected output is:

    origin  https://github.com/<user>/edk2-TemplateSpecification.git (fetch)
origin  https://github.com/<user>/edk2-TemplateSpecification.git (push)
tianocore-docs  https://github.com/tianocore-docs/edk2-TemplateSpecification.git (fetch)
tianocore-docs  https://github.com/tianocore-docs/edk2-TemplateSpecification.git (push)

  • Checkout master branch

    git checkout master

  • If a fork and clone were performed before from a different document edit, then the following commands will sync the local master branch with the master branch in the tianocore-docs repository and also syncs the master branch in the developer's fork with the master branch in the tianocore-docs repository.

    git fetch tianocore-docs
git fetch origin
git checkout master
git rebase tianocore-docs/master
git push origin HEAD:master

  • Create branch to work on document bug fix or feature request

    git checkout master
git checkout -b Bugzilla_<ID>_<Title>

  • If changes are made to the document by others during the edit process, then the following command updates the local branch from tianocore-docs. If there are any merge conflicts, then those must be resolved locally.

    git fetch tianocore-docs
git rebase tianocore-docs/master

  • Edit README.md file and add link to Bugzilla issue in Revision History. The following is an example line from the Revision History of the _EDK II Build Specification _.

    |            | [#481](https://bugzilla.tianocore.org/show_bug.cgi?id=481) Build Spec: add clarification for not used Pcd that build tool will not do additional checks on its value |               |

  • Edit files to resolve the feature request or bug fix. Standard text editors can be used for small changes. Markdown editors can be used for more complex changes.

  • Generate published versions of the document to review changes and format.

    gitbook pdf
gitbook mobi
gitbook epub
gitbook serve

    Review HTML version using a browser at http://localhost:4000

    Use a PDF viewer to review book.pdf

    Use ebook viewer to review book.mobi and book.epub

    Note: The command gitbook install must be run once before any of the publish commands are used to install any required gitbook plugins.

  • Commit changes to local branch using the Commit Message format that includes the link to the Bugzilla issue. The following is an example from the EDK II Build Specification.

    Add EBNF for --pcd flag command line flag

https://bugzilla.tianocore.org/show_bug.cgi?id=523

Cc: Liming Gao <[email protected]>
Cc: Yonghong Zhu <[email protected]>
Cc: Kevin W Shaw <[email protected]>
Contributed-under: TianoCore Contribution Agreement 1.1
Signed-off-by: Michael Kinney <[email protected]>

  • Use PatchCheck.py from the edk2 project to verify the commits in the local branch. Fix all issues and update local commits.

    PatchCheck.py master..

  • Push changes to the personal fork of the document. WARNING: This makes the changes public.

    git push --set-upstream origin Bugzilla_<ID>_<Title>

    The --dry-run flag can be used to review the set of commits before they are pushed.

    git push --dry-run --set-upstream origin Bugzilla_<ID>_<Title>

  • Send patch review email to edk2-devel with changes between current branch and master. Always add a cover letter and add links to the developer's public branch and GitHub word difference view of each commit in the series from the developer's public branch.

    git send-email --annotate --cover-letter --subject-prefix="edk2-BuildSpecification PATCH" --to [email protected] master

    If addition versions need to be sent for review, then add Vn at the end of the subject. The following example is for patch review version 4.

    git send-email --annotate --cover-letter --subject-prefix="edk2-BuildSpecification PATCH V4" --to [email protected] master

    The following is an example of a cover letter. Notice that ?w=1 is added to the end of each commit. The forces the use of the GitHub word difference feature.

    [edk2-BuildSpecification PATCH] Add EBNF for --pcd flag command line flag

https://bugzilla.tianocore.org/show_bug.cgi?id=523

GitHub branch for review:

* https://github.com/mdkinney/edk2-BuildSpecification/tree/Bugzilla_523_EbnfPcdCommandLineOption

GitHub word diff view of the patches in this series:

* [1/1] https://github.com/mdkinney/edk2-BuildSpecification/commit/7f8868c5df4ab39aa6c7ab8f07202d76eba381b3?w=1

Cc: Liming Gao <[email protected]>
Cc: Yonghong Zhu <[email protected]>
Cc: Kevin W Shaw <[email protected]>
Contributed-under: TianoCore Contribution Agreement 1.1
Signed-off-by: Michael Kinney <[email protected]>

Michael Kinney (1):
  Add EBNF for --pcd flag command line flag

 README.md                               |  3 ++-
 appendix_d_buildexe_command/d4_usage.md | 29 +++++++++++++++++++++++++++++
 2 files changed, 31 insertions(+), 1 deletion(-)

  • Once the patch review email is accepted by the reviewers with a Reviewed-by email on edk2-devel, update the commit message with the Reviewed-by lines. The following is the same example from above with this line added.

    Add EBNF for --pcd flag command line flag

https://bugzilla.tianocore.org/show_bug.cgi?id=523

Cc: Liming Gao <[email protected]>
Cc: Yonghong Zhu <[email protected]>
Cc: Kevin W Shaw <[email protected]>
Contributed-under: TianoCore Contribution Agreement 1.1
Signed-off-by: Michael Kinney <[email protected]>
Reviewed-by: Yonghong Zhu <[email protected]>

  • Use PatchCheck.py from the edk2 project to verify the commits in the local branch. Fix all issues and update local commits.

    PatchCheck.py master..

  • Push changes from local branch with the approved changed the tianocore-docs repository. WARNING: This makes the change public in the official repository and triggers the GitBook server to publish a new Draft release of the document.

    git push tianocore-docs HEAD:master

    The --dry-run flag can be used to verify the set of commits without actually pushing them.

    git push --dry-run tianocore-docs HEAD:master

  • Update Bugzilla issue adding a new comment with the link(s) to the GitHub commits. The following is an example comment. Also update the status of the issue to "Resolved" and "Fixed".

    Commit

https://github.com/tianocore-docs/edk2-BuildSpecification/commit/febd90bad29928809f93245b71e1371ca3ef45fe

Back to TianoCore Documents Overview

Clone this wiki locally