From c7969c64bb1d8b667efc3c3abe48f9e1bec1d1f2 Mon Sep 17 00:00:00 2001 From: Scott Rifenbark Date: Thu, 15 Jun 2017 09:11:09 -0700 Subject: dev-manual, ref-manual: Moved "Workflows" section to ref-manual Fixes [YOCTO #11630] I moved the "Workflows" section to the ref-manual. This section is primarily concepts and needs to be out of the dev-manual, which is being reconstituted into a "how-to" manual. (From yocto-docs rev: 2f8bfaac3da9e2d7042ea381a3e8957f96b5bf5a) Signed-off-by: Scott Rifenbark Signed-off-by: Richard Purdie --- documentation/dev-manual/dev-manual-newbie.xml | 148 ---------------------- documentation/dev-manual/figures/git-workflow.png | Bin 26586 -> 0 bytes 2 files changed, 148 deletions(-) delete mode 100644 documentation/dev-manual/figures/git-workflow.png (limited to 'documentation/dev-manual') 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/dev-manual/figures/git-workflow.png deleted file mode 100644 index e401330a12..0000000000 Binary files a/documentation/dev-manual/figures/git-workflow.png and /dev/null differ -- cgit v1.2.3-54-g00ecf