From 30ad0a889646508b568e07810e207e92a80beb6d Mon Sep 17 00:00:00 2001 From: Scott Rifenbark Date: Thu, 22 Feb 2018 12:56:11 -0800 Subject: getting-started: Applied some minor edits to the Git workflow section. (From yocto-docs rev: 15eb983db02b352fd70de6cb3ef2c63e82fa4420) Signed-off-by: Scott Rifenbark Signed-off-by: Richard Purdie --- .../getting-started-development-environment.xml | 44 +++++++++++++--------- 1 file changed, 26 insertions(+), 18 deletions(-) (limited to 'documentation/getting-started') diff --git a/documentation/getting-started/getting-started-development-environment.xml b/documentation/getting-started/getting-started-development-environment.xml index f7d646c2b7..0c08859ea0 100644 --- a/documentation/getting-started/getting-started-development-environment.xml +++ b/documentation/getting-started/getting-started-development-environment.xml @@ -317,6 +317,10 @@ Git Workflows and the Yocto Project + Developing using the Yocto Project likely requires the use of + Git. + Git is a free, open source distributed version control system + used as part of many collaborative design environments. This section provides workflow concepts using the Yocto Project and Git. In particular, the information covers basic practices that describe @@ -328,22 +332,24 @@ - 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. + The Yocto Project files are maintained using Git in "branches" + whose Git histories track every change and whose structures + provide 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. + responsible for the integrity of 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. + most recent builds of a 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 + + For information on finding out who is responsible for (maintains) + a particular area of code in the Yocto Project, see the "Submitting a Change to the Yocto Project" section of the Yocto Project Development Tasks Manual. @@ -357,7 +363,7 @@ of the Source Repositories organized within the "Poky Support" area. - These branches temporarily hold changes to the project that have been + These branches hold changes (commits) 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 @@ -367,20 +373,20 @@ Developers (including contributing community members) create and - maintain cloned repositories of the upstream "master" branch. + maintain cloned repositories of upstream branches. 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. + they "push" the change to the appropriate "contrib" repository. Developers are responsible for keeping their local repository - up-to-date with "master". + up-to-date with whatever upstream branch they are working against. 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 + All this work is done locally on the development host before anything is pushed to a "contrib" area and examined at the maintainer’s level. @@ -388,7 +394,7 @@ 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". + the maintainer include them into an upstream branch. This process is called “submitting a patch” or "submitting a change." For information on submitting patches and changes, see the "Submitting a Change to the Yocto Project" @@ -397,7 +403,7 @@ To summarize the development workflow: a single point of entry - exists for changes into the project’s "master" branch of the + exists for changes into a "master" or development 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. @@ -422,9 +428,11 @@ 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 + the maintainer to more easily include or refuse changes. + + + Make Complete 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. @@ -434,7 +442,7 @@ Use Branches Liberally: It is very easy to create, use, and delete local branches in - your working Git repository. + your working Git repository on the development host. 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. -- cgit v1.2.3-54-g00ecf