diff --git a/documentation/Makefile b/documentation/Makefile index 131c0b7f33..6a2f22e40e 100644 --- a/documentation/Makefile +++ b/documentation/Makefile @@ -129,7 +129,7 @@ TARFILES = dev-style.css dev-manual.html \ else TARFILES = dev-style.css dev-manual.html \ figures/bsp-dev-flow.png \ - figures/dev-title.png figures/git-workflow.png \ + figures/dev-title.png \ figures/kernel-dev-flow.png \ figures/kernel-overview-1.png figures/kernel-overview-2-generic.png \ figures/recipe-workflow.png \ @@ -271,7 +271,7 @@ TARFILES = ref-manual.html ref-style.css figures/poky-title.png \ figures/analysis-for-package-splitting.png figures/image-generation.png \ figures/sdk-generation.png figures/building-an-image.png \ figures/build-workspace-directory.png figures/source-repos.png \ - figures/index-downloads.png figures/yp-download.png + figures/index-downloads.png figures/yp-download.png figures/git-workflow.png MANUALS = $(DOC)/$(DOC).html $(DOC)/eclipse FIGURES = figures STYLESHEET = $(DOC)/*.css diff --git a/documentation/dev-manual/dev-manual-newbie.xml b/documentation/dev-manual/dev-manual-newbie.xml index aca292063e..c2147b39e7 100644 --- a/documentation/dev-manual/dev-manual-newbie.xml +++ b/documentation/dev-manual/dev-manual-newbie.xml @@ -617,154 +617,6 @@ -
- Workflows - - - This section provides some overview on workflows using Git. - In particular, the information covers basic practices that describe roles and actions in a - collaborative development environment. - Again, if you are familiar with this type of development environment, you might want to just - skip this section. - - - - The Yocto Project files are maintained using Git in a "master" branch whose Git history - tracks every change and whose structure provides branches for all diverging functionality. - Although there is no need to use Git, many open source projects do so. - For the Yocto Project, a key individual called the "maintainer" is responsible for the "master" - branch of a given Git repository. - The "master" branch is the “upstream” repository where the final builds of the project occur. - The maintainer is responsible for accepting changes from other developers and for - organizing the underlying branch structure to reflect release strategies and so forth. - For information on finding out who is responsible for (maintains) - a particular area of code, see the - "How to Submit a Change" - section. - - - - - The project also has an upstream contribution Git repository named - poky-contrib. - You can see all the branches in this repository using the web interface - of the - Source Repositories organized - within the "Poky Support" area. - These branches temporarily hold changes to the project that have been - submitted or committed by the Yocto Project development team and by - community members who contribute to the project. - The maintainer determines if the changes are qualified to be moved - from the "contrib" branches into the "master" branch of the Git - repository. - - - - Developers (including contributing community members) create and maintain cloned repositories - of the upstream "master" branch. - These repositories are local to their development platforms and are used to develop changes. - When a developer is satisfied with a particular feature or change, they "push" the changes - to the appropriate "contrib" repository. - - - - Developers are responsible for keeping their local repository up-to-date with "master". - They are also responsible for straightening out any conflicts that might arise within files - that are being worked on simultaneously by more than one person. - All this work is done locally on the developer’s machines before anything is pushed to a - "contrib" area and examined at the maintainer’s level. - - - - A somewhat formal method exists by which developers commit changes and push them into the - "contrib" area and subsequently request that the maintainer include them into "master" - This process is called “submitting a patch” or "submitting a change." - For information on submitting patches and changes, see the - "How to Submit a Change" section. - - - - To summarize the environment: a single point of entry exists for - changes into the project’s "master" branch of the Git repository, - which is controlled by the project’s maintainer. - And, a set of developers exist who independently develop, test, and - submit changes to "contrib" areas for the maintainer to examine. - The maintainer then chooses which changes are going to become a - permanent part of the project. - - - - - - - - While each development environment is unique, there are some best practices or methods - that help development run smoothly. - The following list describes some of these practices. - For more information about Git workflows, see the workflow topics in the - Git Community Book. - - Make Small Changes: It is best to keep the changes you commit - small as compared to bundling many disparate changes into a single commit. - This practice not only keeps things manageable but also allows the maintainer - to more easily include or refuse changes. - It is also good practice to leave the repository in a state that allows you to - still successfully build your project. In other words, do not commit half of a feature, - then add the other half as a separate, later commit. - Each commit should take you from one buildable project state to another - buildable state. - Use Branches Liberally: It is very easy to create, use, and - delete local branches in your working Git repository. - You can name these branches anything you like. - It is helpful to give them names associated with the particular feature or change - on which you are working. - Once you are done with a feature or change and have merged it - into your local master branch, simply discard the temporary - branch. - Merge Changes: The git merge - command allows you to take the - changes from one branch and fold them into another branch. - This process is especially helpful when more than a single developer might be working - on different parts of the same feature. - Merging changes also automatically identifies any collisions or "conflicts" - that might happen as a result of the same lines of code being altered by two different - developers. - Manage Branches: Because branches are easy to use, you should - use a system where branches indicate varying levels of code readiness. - For example, you can have a "work" branch to develop in, a "test" branch where the code or - change is tested, a "stage" branch where changes are ready to be committed, and so forth. - As your project develops, you can merge code across the branches to reflect ever-increasing - stable states of the development. - Use Push and Pull: The push-pull workflow is based on the - concept of developers "pushing" local commits to a remote repository, which is - usually a contribution repository. - This workflow is also based on developers "pulling" known states of the project down into their - local development repositories. - The workflow easily allows you to pull changes submitted by other developers from the - upstream repository into your work area ensuring that you have the most recent software - on which to develop. - The Yocto Project has two scripts named create-pull-request and - send-pull-request that ship with the release to facilitate this - workflow. - You can find these scripts in the scripts - folder of the - Source Directory. - For information on how to use these scripts, see the - "Using Scripts to Push a Change Upstream and Request a Pull" section. - - Patch Workflow: This workflow allows you to notify the - maintainer through an email that you have a change (or patch) you would like considered - for the "master" branch of the Git repository. - To send this type of change, you format the patch and then send the email using the Git commands - git format-patch and git send-email. - For information on how to use these scripts, see the - "How to Submit a Change" - section. - - - -
-
Submitting a Defect Against the Yocto Project diff --git a/documentation/dev-manual/figures/git-workflow.png b/documentation/ref-manual/figures/git-workflow.png similarity index 100% rename from documentation/dev-manual/figures/git-workflow.png rename to documentation/ref-manual/figures/git-workflow.png diff --git a/documentation/ref-manual/ref-development-environment.xml b/documentation/ref-manual/ref-development-environment.xml index 5b0557d905..08e790b7a2 100644 --- a/documentation/ref-manual/ref-development-environment.xml +++ b/documentation/ref-manual/ref-development-environment.xml @@ -65,6 +65,197 @@
+
+ Workflows + + + This section provides workflow concepts using the Yocto Project and + Git. + In particular, the information covers basic practices that describe + roles and actions in a collaborative development environment. + + If you are familiar with this type of development environment, you + might not want to read this section. + + + + + The Yocto Project files are maintained using Git in "master" + branches whose Git histories track every change and whose structures + provides branches for all diverging functionality. + Although there is no need to use Git, many open source projects do so. + + + + For the Yocto Project, a key individual called the "maintainer" is + responsible for the "master" branch of a given Git repository. + The "master" branch is the “upstream” repository from which final or + most recent builds of the project occur. + The maintainer is responsible for accepting changes from other + developers and for organizing the underlying branch structure to + reflect release strategies and so forth. + For information on finding out who is responsible for (maintains) + a particular area of code, see the + "How to Submit a Change" + section of the Yocto Project Development Manual. + + + + + The Yocto Project poky Git repository also has an + upstream contribution Git repository named + poky-contrib. + You can see all the branches in this repository using the web interface + of the + Source Repositories organized + within the "Poky Support" area. + These branches temporarily hold changes to the project that have been + submitted or committed by the Yocto Project development team and by + community members who contribute to the project. + The maintainer determines if the changes are qualified to be moved + from the "contrib" branches into the "master" branch of the Git + repository. + + + + Developers (including contributing community members) create and + maintain cloned repositories of the upstream "master" branch. + The cloned repositories are local to their development platforms and + are used to develop changes. + When a developer is satisfied with a particular feature or change, + they "push" the changes to the appropriate "contrib" repository. + + + + Developers are responsible for keeping their local repository + up-to-date with "master". + They are also responsible for straightening out any conflicts that + might arise within files that are being worked on simultaneously by + more than one person. + All this work is done locally on the developer’s machine before + anything is pushed to a "contrib" area and examined at the maintainer’s + level. + + + + A somewhat formal method exists by which developers commit changes + and push them into the "contrib" area and subsequently request that + the maintainer include them into "master". + This process is called “submitting a patch” or "submitting a change." + For information on submitting patches and changes, see the + "How to Submit a Change" + section in the Yocto Project Development Manual. + + + + To summarize the development workflow: a single point of entry + exists for changes into the project’s "master" branch of the + Git repository, which is controlled by the project’s maintainer. + And, a set of developers exist who independently develop, test, and + submit changes to "contrib" areas for the maintainer to examine. + The maintainer then chooses which changes are going to become a + permanent part of the project. + + + + + + + + While each development environment is unique, there are some best + practices or methods that help development run smoothly. + The following list describes some of these practices. + For more information about Git workflows, see the workflow topics in + the + Git Community Book. + + + Make Small Changes: + It is best to keep the changes you commit small as compared to + bundling many disparate changes into a single commit. + This practice not only keeps things manageable but also allows + the maintainer to more easily include or refuse changes. + + It is also good practice to leave the repository in a + state that allows you to still successfully build your project. + In other words, do not commit half of a feature, + then add the other half as a separate, later commit. + Each commit should take you from one buildable project state + to another buildable state. + + + Use Branches Liberally: + It is very easy to create, use, and delete local branches in + your working Git repository. + You can name these branches anything you like. + It is helpful to give them names associated with the particular + feature or change on which you are working. + Once you are done with a feature or change and have merged it + into your local master branch, simply discard the temporary + branch. + + + Merge Changes: + The git merge command allows you to take + the changes from one branch and fold them into another branch. + This process is especially helpful when more than a single + developer might be working on different parts of the same + feature. + Merging changes also automatically identifies any collisions + or "conflicts" that might happen as a result of the same lines + of code being altered by two different developers. + + + Manage Branches: + Because branches are easy to use, you should use a system + where branches indicate varying levels of code readiness. + For example, you can have a "work" branch to develop in, a + "test" branch where the code or change is tested, a "stage" + branch where changes are ready to be committed, and so forth. + As your project develops, you can merge code across the + branches to reflect ever-increasing stable states of the + development. + + + Use Push and Pull: + The push-pull workflow is based on the concept of developers + "pushing" local commits to a remote repository, which is + usually a contribution repository. + This workflow is also based on developers "pulling" known + states of the project down into their local development + repositories. + The workflow easily allows you to pull changes submitted by + other developers from the upstream repository into your + work area ensuring that you have the most recent software + on which to develop. + The Yocto Project has two scripts named + create-pull-request and + send-pull-request that ship with the + release to facilitate this workflow. + You can find these scripts in the scripts + folder of the + Source Directory. + For information on how to use these scripts, see the + "Using Scripts to Push a Change Upstream and Request a Pull" + section in the Yocto Project Development Manual. + + + Patch Workflow: + This workflow allows you to notify the maintainer through an + email that you have a change (or patch) you would like + considered for the "master" branch of the Git repository. + To send this type of change, you format the patch and then + send the email using the Git commands + git format-patch and + git send-email. + For information on how to use these scripts, see the + "How to Submit a Change" + section in the Yocto Project Development Manual. + + + +
+
Yocto Project Source Repositories