From owner-dev-commits-doc-all@freebsd.org Fri Apr 9 20:17:56 2021 Return-Path: Delivered-To: dev-commits-doc-all@mailman.nyi.freebsd.org Received: from mx1.freebsd.org (mx1.freebsd.org [IPv6:2610:1c1:1:606c::19:1]) by mailman.nyi.freebsd.org (Postfix) with ESMTP id EB4D75DBA0C for ; Fri, 9 Apr 2021 20:17:56 +0000 (UTC) (envelope-from git@FreeBSD.org) Received: from mxrelay.nyi.freebsd.org (mxrelay.nyi.freebsd.org [IPv6:2610:1c1:1:606c::19:3]) (using TLSv1.3 with cipher TLS_AES_256_GCM_SHA384 (256/256 bits) key-exchange X25519 server-signature RSA-PSS (4096 bits) server-digest SHA256 client-signature RSA-PSS (4096 bits) client-digest SHA256) (Client CN "mxrelay.nyi.freebsd.org", Issuer "R3" (verified OK)) by mx1.freebsd.org (Postfix) with ESMTPS id 4FH8ZX5FxHz4XJb; Fri, 9 Apr 2021 20:17:56 +0000 (UTC) (envelope-from git@FreeBSD.org) Received: from gitrepo.freebsd.org (gitrepo.freebsd.org [IPv6:2610:1c1:1:6068::e6a:5]) (using TLSv1.3 with cipher TLS_AES_256_GCM_SHA384 (256/256 bits) key-exchange X25519 server-signature RSA-PSS (4096 bits) server-digest SHA256) (Client did not present a certificate) by mxrelay.nyi.freebsd.org (Postfix) with ESMTPS id A7FA92424F; Fri, 9 Apr 2021 20:17:56 +0000 (UTC) (envelope-from git@FreeBSD.org) Received: from gitrepo.freebsd.org ([127.0.1.44]) by gitrepo.freebsd.org (8.16.1/8.16.1) with ESMTP id 139KHuBB031622; Fri, 9 Apr 2021 20:17:56 GMT (envelope-from git@gitrepo.freebsd.org) Received: (from git@localhost) by gitrepo.freebsd.org (8.16.1/8.16.1/Submit) id 139KHugY031621; Fri, 9 Apr 2021 20:17:56 GMT (envelope-from git) Date: Fri, 9 Apr 2021 20:17:56 GMT Message-Id: <202104092017.139KHugY031621@gitrepo.freebsd.org> To: doc-committers@FreeBSD.org, dev-commits-doc-all@FreeBSD.org From: "George V. Neville-Neil" Subject: git: e47e964a9d - main - Rough draft on collaboration using github MIME-Version: 1.0 Content-Type: text/plain; charset=utf-8 Content-Transfer-Encoding: 8bit X-Git-Committer: gnn X-Git-Repository: doc X-Git-Refname: refs/heads/main X-Git-Reftype: branch X-Git-Commit: e47e964a9d36c7248d97aad74a080c5223fb9f7e Auto-Submitted: auto-generated X-BeenThere: dev-commits-doc-all@freebsd.org X-Mailman-Version: 2.1.34 Precedence: list List-Id: Commit messages for all branches of the doc repository List-Unsubscribe: , List-Archive: List-Post: List-Help: List-Subscribe: , X-List-Received-Date: Fri, 09 Apr 2021 20:17:57 -0000 The branch main has been updated by gnn (src committer): URL: https://cgit.FreeBSD.org/doc/commit/?id=e47e964a9d36c7248d97aad74a080c5223fb9f7e commit e47e964a9d36c7248d97aad74a080c5223fb9f7e Author: George V. Neville-Neil AuthorDate: 2021-04-09 20:16:36 +0000 Commit: George V. Neville-Neil CommitDate: 2021-04-09 20:17:49 +0000 Rough draft on collaboration using github --- .../en/articles/committers-guide/_index.adoc | 87 ++++++++++++++++++++++ 1 file changed, 87 insertions(+) diff --git a/documentation/content/en/articles/committers-guide/_index.adoc b/documentation/content/en/articles/committers-guide/_index.adoc index fa65ede180..6142719316 100644 --- a/documentation/content/en/articles/committers-guide/_index.adoc +++ b/documentation/content/en/articles/committers-guide/_index.adoc @@ -2019,6 +2019,93 @@ git log refs/freebsd/vendor/zlib/1.2.10 .... would look at the log for the vendor branch for zlib starting at 1.2.10. +=== Collaborating with Others + +One of the keys to good software development on a project as large as FreeBSD is the ability to collaborate with others before you push your changes to the tree. The FreeBSD project's git repositories do not, yet, allow user created branches to be pushed to the repository, and therefore if you wish to share your changes with others you must use another mechanism, such as a hosted GitLab or github, in order to share changes in a user generate branch. + +The following instructions show how to set up a user generated branch, based on the FreeBSD main branch, and push it to github. + +Before you begin, make sure that your local git repo is up to date and has the correct origins set as shown above. + +[source,shell] +```` +% git remote -v +freebsd https://git.freebsd.org/src.git (fetch) +freebsd ssh://git@gitrepo.freebsd.org/src.git (push) +```` + +The first step is to create a fork of https://github.com/freebsd/freebsd-src[FreeBSD] on github. +The destination of the fork should be your own, personal, github account (gvnn3 in my case). + +Now add a remote that points to your fork: +.... +% git remote add collab git@github.com:gvnn3/freebsd-src.git +% git remote -v +collab git@github.com:gvnn3/freebsd-src.git (fetch) +collab git@github.com:gvnn3/freebsd-src.git (push) +freebsd https://git.freebsd.org/src.git (fetch) +freebsd ssh://git@gitrepo.freebsd.org/src.git (push) +.... +With this in place you can create a local branch as shown above. + +.... +% git checkout -b gnn-collab +.... + +Make whatever modifications you wish in your branch. Build, test, and +once you're ready to collaborate with others it's time to push your +changes into your hosted branch. Before you can push you'll have to +set the appropriate upstream, as git will tell you the first time you +try to push to your +collab+ remote: + +.... +% git push collab +fatal: The current branch gnn-collab has no upstream branch. +To push the current branch and set the remote as upstream, use + + git push --set-upstream collab gnn-collab +.... + +Setting the push as +git+ advises allows it so succeed: + +.... +% git push --set-upstream collab gnn-collab +X11 forwarding request failed on channel 0 +Enumerating objects: 20486, done. +Counting objects: 100% (20486/20486), done. +Delta compression using up to 8 threads +Compressing objects: 100% (12202/12202), done. +Writing objects: 100% (20180/20180), 56.25 MiB | 13.15 MiB/s, done. +Total 20180 (delta 11316), reused 12972 (delta 7770), pack-reused 0 +remote: Resolving deltas: 100% (11316/11316), completed with 247 local objects. +remote: +remote: Create a pull request for 'gnn-collab' on GitHub by visiting: +remote: https://github.com/gvnn3/freebsd-src/pull/new/gnn-collab +remote: +To github.com:gvnn3/freebsd-src.git + * [new branch] gnn-collab -> gnn-collab +Branch 'gnn-collab' set up to track remote branch 'gnn-collab' from 'collab'. +.... + +Subsequent changes to the same branch will push correctly by default: + +.... +% git push +X11 forwarding request failed on channel 0 +Enumerating objects: 4, done. +Counting objects: 100% (4/4), done. +Delta compression using up to 8 threads +Compressing objects: 100% (2/2), done. +Writing objects: 100% (3/3), 314 bytes | 1024 bytes/s, done. +Total 3 (delta 1), reused 1 (delta 0), pack-reused 0 +remote: Resolving deltas: 100% (1/1), completed with 1 local object. +To github.com:gvnn3/freebsd-src.git + 9e5243d7b659..cf6aeb8d7dda gnn-collab -> gnn-collab +.... + +At this point your work is now in your branch on +github+ and you can +share the link with other collaborators. + [[vcs-history]] == Version Control History