Differences

This shows you the differences between two versions of the page.

--- googlecodein:gettingstarted [2011/11/26 17:57] – GavinAtkinson
+++ googlecodein:gettingstarted [2020/12/30 02:52] (current) – Remove 1 broken hyperlink. SashaVigole
@@ Line 1: / Line 1: @@
-The easiest way to get started with
+====== Getting Started ======
-OLD PAGE:
+Some of the %%FreeBSD%% tasks may seem daunting, especially to those who have no prior experience with %%FreeBSD%% or similar operating systems.  This page should provide enough information to enable you to get started and in a position to work on the tasks as quickly as possible.
-Most of the Google Code-In tasks require the %%FreeBSD%% source code to have been checked out.  There are several ways of doing this, each with advantages and disadvantages.  The method described here is probably the easiest way of obtaining the source for small-scale work.
+If you have any problems with any of the instructions here, please do feel free to talk to your mentor, or ask on IRC.  There are many mentors available in #freebsd-soc on EFnet, feel free to pop in and say hello even if you are not having issues!
-The following documentation assumes that you are using %%FreeBSD%%, either on a real machine, or in a virtual environment, and that your system has Internet access.
+===== Requirements for Google Code-In tasks =====
-**Note that it is recommended that you do not update your tree whilst working on your tasks, as this combined with the approach documented here will cause your changes to be overwritten each time you update.**
+Most of the Google Code-In tasks require the following:
-If you have any problems with any of this, please do feel free to talk to your mentor, or ask on IRC.  There are many mentors available in #freebsd-soc on EFnet.
+  * A %%FreeBSD%% system (in a [[/VirtualBox|VirtualBox]] Virtual Machine) installed on your computer.  A pre-prepared image along with instructions for use can be found below.  It is recommended that students new to %%FreeBSD%% use this pre-prepared image.
+  * Knowledge of the documentation guidelines for the %%FreeBSD%% project: http://www.freebsd.org/doc/en_US.ISO8859-1/books/fdp-primer/
+  * A copy of the %%FreeBSD%% documentation tree checked out from the %%FreeBSD%% doc repository.  The pre-prepared VM image already contains this, or see below for details on how to obtain this.
+  * Knowledge on how to research information on the internet
+  * Thorough work style
-====== Documentation tree ======
+===== Using the pre-prepared VM images =====
-As root, create a file named ''%%doc-supfile%%'' containing:
+The easiest way to get started with the Google Code-In tasks is to download the pre-made Virtual Machine image.  This is available for download from ''%%people.FreeBSD.org/~gavin/FreeBSD9.0_GCIN.ova%%'' (2.2Gb download, SHA256 aa212d1ca717a6a9800e67462ec3456c5e652fea1bba09bb649d6fa3cb0c6ea6).  It is known to work with [[/VirtualBox|VirtualBox]] 4, but should also work with minimal effort on anything supporting the OVF format for virtual machine images, including VMware.
-<code>
+Once the VM image has been imported, boot it.  The image has been set up so that all your work can either be done on the VM console itself, or over SSH.  After the machine has booted, basic instructions will be shown on the console, including the IP address that the virtual machine has been given.  You can SSH to this IP address (using the gcin account) if you wish to work over SSH rather than directly on the console.  GNOME is also available in the VM image, should you prefer to use the VM directly.
-*default host=cvsup8.FreeBSD.org
-*default base=/var/db
-*default prefix=/usr
-*default release=cvs tag=.
-*default delete use-rel-suffix
-*default compress
-doc-all
+There are two accounts set up:
-#www
-</code>
-For most tasks, the website source is not necessary.  If you require it (or indeed, just want to see it), uncomment the ''%%www%%'' line.  Be aware that the website is quite large, so make sure you have enough disk space.
+| username | password |
+| root | gcin |
+| gcin | gcin |
-Then, still as root, run ''%%"csup doc-supfile"%%''.  This will drop the %%FreeBSD%% doc source code into ''%%/usr/doc%%'' (and the website code into ''%%/usr/www%%'' if that line is uncommented).  Run this same command every time you want to update your local copy to match the "live" copy, but beware of the note above.
+You should only need to use the gcin username/password for most tasks.
-Once you have the documentation tree, find the file that you want to work on, and make a copy of it. For example, if your task involves making changes to the %%FreeBSD%% Handbook bibliography, make a copy of it:
+In the home directory of the gcin users, a directory called "''%%gcin2011%%''" exists, containing checkouts from the repositories most likely to be useful during GCIN:
-''%%cp -p /usr/doc/en_US.ISO8859-1/books/handbook/bibliography/chapter.sgml /usr/doc/en_US.ISO8859-1/books/handbook/bibliography/chapter.old.sgml%%''
+| doc | The %%FreeBSD%% Documentation tree |
+| head | %%FreeBSD%% source code for -CURRENT |
+| stable/9 | %%FreeBSD%% source code for the 9-STABLE branch |
-Then, make your edits to ''%%/usr/doc/en_US.ISO8859-1/books/handbook/bibliography/chapter.sgml%%''
+All three trees are checked out using Subversion.
-===== Testing your changes =====
+==== Working on the FreeBSD documentation tree ====
-Once you are ready to test your changes, follow the instructions at ''%%http://www.freebsd.org/doc/en/books/fdp-primer/overview-quick-start.html%%''
+(to be written). See http://www.freebsd.org/doc/en/books/fdp-primer/
-===== Submitting your changes =====
+=== Working on existing documentation ===
+=== Testing ===
-As you made a copy of the file before you made changes, you can produce a diff from it with:
+==== Working on the FreeBSD source tree ====
-''%%diff -uw /usr/doc/en_US.ISO8859-1/books/handbook/bibliography/chapter.old.sgml /usr/doc/en_US.ISO8859-1/books/handbook/bibliography/chapter.sgml > /var/tmp/gcin-taskname.diff%%''
+(to be written)
+=== Working on existing documentation ===
+=== Testing ===
-This file can then be submitted to your task mentor(s) during the task, and uploaded to Google once you feel the task is complete.
+==== Submitting your work ====
+The preferred format for submitting work done is in diff format.  To produce a diff of your work, use the "svn diff" command.
+For example, to create a diff of changes made to the %%FreeBSD%% handbook, the following command should be used:
+''%%svn diff doc/en_US.ISO8859-1/books/handbook/ > /var/tmp/gcin-handbook.diff%%''
+Then, upload the file ''%%/var/tmp/gcin-handbook.diff%%'' to Google Melange.
+Note, however, that any new files (i.e. files created rather than modified) will not be included in the output of "''%%svn diff%%''" and should be uploaded separately.
+==== Updating the source code checkouts ====
+All the supplied trees can be updated using "svn update".  For example:
+''%%svn update gcin2011/doc%%''
+----
+====== Working on tasks without using the prepared VM images ======
+There are several ways of obtaining the source code, each with advantages and disadvantages.  This document describes just one approach, and users experienced with source control may prefer to use an approach they are more familiar with.
+The following assumes that you are using %%FreeBSD%%, either on a real machine, or in a virtual environment, and that your system has Internet access.
+===== Obtaining the FreeBSD Documentation tree =====
+The %%FreeBSD%% Project currently still uses CVS to store its documentation.  In order to make things easier for GCIN students, we have started exporting the doc tree to a Google Code svn repository, which should prove easier for students unfamiliar with CVS to work with.
+Check the tree out with:
+''%%svn checkout http://freebsd9-documentation.googlecode.com/svn/branches/gcin2011/doc doc%%''
+Once you have obtained the code, please see the top section of this page for how to work with it, test your work, and submit your changes.
+===== Obtaining the FreeBSD source Code =====
+As the %%FreeBSD%% source code is held in SVN, this can be checked out directly:
+''%%svn co svn://svn.freebsd.org/base/head/%%''
+Once you have obtained the code, please see the top section of this page for how to work with it, test your work, and submit your changes.