From mboxrd@z Thu Jan 1 00:00:00 1970 From: John Darrington Subject: Re: [PATCH] Quick-start guide Date: Mon, 13 Jun 2016 02:40:10 +0200 Message-ID: <20160613004010.GA28724@jocasta.intra> References: Mime-Version: 1.0 Content-Type: multipart/signed; micalg=pgp-sha1; protocol="application/pgp-signature"; boundary="LZvS9be/3tNcYl/X" Return-path: Received: from eggs.gnu.org ([2001:4830:134:3::10]:46943) by lists.gnu.org with esmtp (Exim 4.71) (envelope-from ) id 1bCFvY-00034K-4L for guix-devel@gnu.org; Sun, 12 Jun 2016 20:40:29 -0400 Received: from Debian-exim by eggs.gnu.org with spam-scanned (Exim 4.71) (envelope-from ) id 1bCFvT-0002pX-VB for guix-devel@gnu.org; Sun, 12 Jun 2016 20:40:27 -0400 Received: from de.cellform.com ([88.217.224.109]:48565 helo=jocasta.intra) by eggs.gnu.org with esmtp (Exim 4.71) (envelope-from ) id 1bCFvT-0002pL-HS for guix-devel@gnu.org; Sun, 12 Jun 2016 20:40:23 -0400 Content-Disposition: inline In-Reply-To: List-Id: "Development of GNU Guix and the GNU System distribution." List-Unsubscribe: , List-Archive: List-Post: List-Help: List-Subscribe: , Errors-To: guix-devel-bounces+gcggd-guix-devel=m.gmane.org@gnu.org Sender: "Guix-devel" To: yoosty@gmail.com Cc: guix-devel@gnu.org --LZvS9be/3tNcYl/X Content-Type: text/plain; charset=us-ascii Content-Disposition: inline Content-Transfer-Encoding: quoted-printable On Sat, Jun 04, 2016 at 01:00:17PM -0700, yoosty@gmail.com wrote: Howdy! =20 This is my first submission, please be gentle ;) =20 Input is definitely welcome. diff --git a/doc/contributing.texi b/doc/contributing.texi index 208c6af..46c652f 100644 --- a/doc/contributing.texi +++ b/doc/contributing.texi @@ -18,6 +18,7 @@ the @file{CODE-OF-CONDUCT} file in the source tree. @menu * Building from Git:: The latest and greatest. * Running Guix Before It Is Installed:: Hacker tricks. +* Quick Setup:: The quick and easy tools * The Perfect Setup:: The right tools. * Coding Style:: Hygiene of the contributor. * Submitting Patches:: Share your work. @@ -153,6 +154,75 @@ the @file{/root/.config/guix/latest} symlink to p= oint to @command{guix} as your user does.} =20 =20 +@node Quick Setup +@section Quick Setup + +So you just want the quick-and-dirty guide? Assuming you have some familiarity +with GNU/Linux systems in general and have installed one several times before +you can probably get started with a few notes while citing +@pxref{GNU Distribution} as necessary. As this is a quick-setup guide we'll use +some example defaults. +The general idea is that you will: What is the purpose of the above paragraph? It does not convey any informa= tion to the reader. Whilst I think it is good to put the reader at ease, this = is=20 overdoing it. Further, it is vague and overly conditional ("Assuming you h= ave ... you can probably ...") which will make the reader feel unsure of himself. = =20 I would replace these three sentances by something short and to the point s= uch=20 as "Setting up Guix involves the following steps:" +@itemize +@item @uref{https://gnu.org/software/guix/download/, Download} the USB installer +@item Transfer the image to a USB stick (@pxref{USB Stick Installatio= n}) +using dd +@item Boot the USB stick +@item Configure @pxref{Preparing for Installation,Networking} +@item Set your @xref{Preparing for Installation,Disk Partitioning} +(using an msdos label instead of a gpt label might be easier at the m= oment) +@item Mount your partitions (e.g. /mnt) +@item Run (again, e.g. /mnt) @command{herd start cow-store /mnt} +@item Create a system configuration file using +@xref{Proceeding with the Installation} and +@xref{Using the Configuration System} as guides. It is suggested to s= tart +with the bare-bones template as you can easily re-configure your syst= em +once it is up. +@item Using /mnt/root/guix_configs/config00.scm as the example config= file +and /mnt as the example install mount point, run +@command{guix system init /mnt/root/guix_configs/config00.scm /mnt} +@item Cross your fingers and grab a beer +@item If you're using reasonably new hardware and a bare-bones config What do you mean by "bare-bones config" and what if the reader is not using= one? or not using new hardware? +then guix should be done before your beverage and you can run Else where you have written "Guix" rather than "guix". +@command{reboot} +@end itemize + +Now you should be ready to rock!=20 I recommend that you avoid cliches like this. Readers for whom English is = a=20 second language, may not be familiar with such expressions. It might confus= e=20 them. Similarly, with "cross your fingers and grab a beer". Instead, be= =20 specific and say something like: "Installation will now proceed. It will t= ake several minutes. If you are using older hardware, then it may take somewhat= =20 longer". And importantly, say what the user should see after the process h= as=20 completed. + Don't forget to set your user passwords. How should the reader do that? + +Of course, you're not here just to have a working system are you, you= want Punctuation. Should read: "... are you? You want..." +to dive in to the source, right? Let's take a quick look at that as w= ell. Again, expressions like "to dive in" might confuse some readers. +This guide assumes that you have at least perused @pxref{Building from Git}. +First you might want to head to +@uref{http://git.savannah.gnu.org/cgit/guix.git, the Guix Git page} a= nd browse +around. We're going to assume that you utilized a bare-bones config a= s per the Who is "we" ? Again, what if he didn't use a "bare-bones config"? +quick install guide above. In this short example you will be shown si= mply +how to change the release version of Guix (not something you will lik= ely do +but an easy and fun example). + +@itemize +@item Install git in to your user's profile: @command{guix package --install git} +@item Create a directory for your git checkout (e.g. @command{mkdir ~/git_repos}) +@item Clone the Guix repository: +@command{cd ~/git_repos/; git clone git://git.sv.gnu.org/guix.git; cd= guix} +@item To make the simple version change: +@code{AC_INIT([GNU Guix], [0.10.0], [bug-guix@@gnu.org], [guix],} +to +@code{AC_INIT([GNU Guix], [0.10.42], [bug-guix@@gnu.org], [guix],} +@item Check your change with: @command{git diff configure.ac} +@item Let Guix set up your Guix build +environment:@command{guix environment guix} +@item Build Guix: +@command{./bootstrap ; ./configure --localstatedir=3D/var ; make} +@item Run the daemon in a pre-installation environment: +@command{sudo ./pre-inst-env guix-daemon --build-users-group=3Dguixbu= ild} +@item Switch to a new terminal +@item Check the pre-installation environement daemon's version: +@command{./git_repos/guix/pre-inst-env guix --version} +@item Your version output should be updated! This sentance is not a part of the procedure. It should appear outside of = the @itemize block +@end itemize + + @node The Perfect Setup @section The Perfect Setup =20 =20 --=20 =20 .:Justin:. --=20 Avoid eavesdropping. Send strong encryted email. PGP Public key ID: 1024D/2DE827B3=20 fingerprint =3D 8797 A26D 0854 2EAB 0285 A290 8A67 719C 2DE8 27B3 See http://sks-keyservers.net or any PGP keyserver for public key. --LZvS9be/3tNcYl/X Content-Type: application/pgp-signature; name="signature.asc" Content-Description: Digital signature -----BEGIN PGP SIGNATURE----- Version: GnuPG v1 iEYEARECAAYFAldeAOoACgkQimdxnC3oJ7PPBgCfTIuRUwROv0tMUJB9/pRDCsYJ MasAn1Xqg7hOPJTD0EIphd91Sw59YfXD =gTcs -----END PGP SIGNATURE----- --LZvS9be/3tNcYl/X--