~vcs-imports/gawk/master

\input texinfo   @c -*-texinfo-*-

@c vim: filetype=texinfo expandtab tabstop=4 shiftwidth=4

@c %**start of header (This is for running Texinfo on a region.)

@setfilename gawkworkflow.info

@settitle GNU Awk Development Workflow

@c %**end of header (This is for running Texinfo on a region.)

@dircategory Text creation and manipulation

@direntry

* Gawk Work Flow: (gawkworkflow).                 Participating in @command{gawk} development.

@end direntry

@dircategory Individual utilities

@direntry

* Gawk Work Flow: (gawkworkflow)Overview.         Participating in @command{gawk} development.

@end direntry

@c With early 2014 texinfo.tex, restore PDF links and colors

@tex

\gdef\linkcolor{0.5 0.09 0.12} % Dark Red

\gdef\urlcolor{0.5 0.09 0.12} % Also

\global\urefurlonlylinktrue

@end tex

@set xref-automatic-section-title

@c The following information should be updated here only!

@c This sets the edition of the document, the version of gawk it

@c applies to and all the info about who's publishing this edition

@c These apply across the board.

@set UPDATE-MONTH March, 2023

@set TITLE Participating in @command{gawk} Development

@set EDITION 0.75

@iftex

@set DOCUMENT booklet

@set CHAPTER chapter

@set APPENDIX appendix

@set SECTION section

@set SUBSECTION subsection

@end iftex

@ifinfo

@set DOCUMENT Info file

@set CHAPTER major node

@set APPENDIX major node

@set SECTION minor node

@set SUBSECTION node

@end ifinfo

@ifhtml

@set DOCUMENT Web page

@set CHAPTER chapter

@set APPENDIX appendix

@set SECTION section

@set SUBSECTION subsection

@end ifhtml

@ifdocbook

@set DOCUMENT booklet

@set CHAPTER chapter

@set APPENDIX appendix

@set SECTION section

@set SUBSECTION subsection

@end ifdocbook

@ifxml

@set DOCUMENT booklet

@set CHAPTER chapter

@set APPENDIX appendix

@set SECTION section

@set SUBSECTION subsection

@end ifxml

@ifplaintext

@set DOCUMENT booklet

@set CHAPTER chapter

@set APPENDIX appendix

@set SECTION section

@set SUBSECTION subsection

@end ifplaintext

@ifnottex

@ifnotdocbook

@macro ii{text}

@i{\text\}

@end macro

@end ifnotdocbook

@end ifnottex

@ifdocbook

@macro ii{text}

@inlineraw{docbook,<lineannotation>\text\</lineannotation>}

@end macro

@end ifdocbook

@c For HTML, spell out email addresses, to avoid problems with

@c address harvesters for spammers.

@ifhtml

@macro EMAIL{real,spelled}

``\spelled\''

@end macro

@end ifhtml

@ifnothtml

@macro EMAIL{real,spelled}

@email{\real\}

@end macro

@end ifnothtml

@c merge the function and variable indexes into the concept index

@ifinfo

@synindex fn cp

@synindex vr cp

@end ifinfo

@iftex

@syncodeindex fn cp

@syncodeindex vr cp

@end iftex

@ifxml

@syncodeindex fn cp

@syncodeindex vr cp

@end ifxml

@ifdocbook

@synindex fn cp

@synindex vr cp

@end ifdocbook

@c If "finalout" is commented out, the printed output will show

@c black boxes that mark lines that are too long.  Thus, it is

@c unwise to comment it out when running a master in case there are

@c overfulls which are deemed okay.

@iftex

@finalout

@end iftex

@copying

@docbook

<para>Published by:</para>

<literallayout class="normal">Free Software Foundation

51 Franklin Street, Fifth Floor

Boston, MA  02110-1301 USA

Phone: +1-617-542-5942

Fax: +1-617-542-2652

Email: <email>gnu@@gnu.org</email>

URL: <ulink url="http://www.gnu.org">http://www.gnu.org/</ulink></literallayout>

<literallayout class="normal">Copyright &copy; 2017, 2018, 2019, 2020, 2022, 2023

Free Software Foundation, Inc.

All Rights Reserved.</literallayout>

@end docbook

@ifnotdocbook

Copyright @copyright{} 2017, 2018, 2019, 2020, 2022, 2023

Free Software Foundation, Inc.

@end ifnotdocbook

@sp 2

This is Edition @value{EDITION} of @cite{@value{TITLE}}.

Permission is granted to copy, distribute and/or modify this document

under the terms of the GNU Free Documentation License, Version 1.3 or

any later version published by the Free Software Foundation; with the

Invariant Sections being ``GNU General Public License'', with the

Front-Cover Texts being ``A GNU Manual'', and with the Back-Cover Texts

as in (a) below.

A copy of the license is included in the section entitled

``GNU Free Documentation License''.

@enumerate a

@item

The FSF's Back-Cover Text is: ``You have the freedom to

copy and modify this GNU manual.''

@end enumerate

@end copying

@c Comment out the "smallbook" for technical review.  Saves

@c considerable paper.  Remember to turn it back on *before*

@c starting the page-breaking work.

@c 4/2002: Karl Berry recommends commenting out this and the

@c `@setchapternewpage odd', and letting users use `texi2dvi -t'

@c if they want to waste paper.

@c @smallbook

@c Uncomment this for the release.  Leaving it off saves paper

@c during editing and review.

@c @setchapternewpage odd

@c @shorttitlepage @value{TITLE}

@titlepage

@title @value{TITLE}

@subtitle Edition @value{EDITION}

@subtitle @value{UPDATE-MONTH}

@author Arnold D.@: Robbins

@ifnotdocbook

@c Include the Distribution inside the titlepage environment so

@c that headings are turned off.  Headings on and off do not work.

@page

@vskip 0pt plus 1filll

Published by:

@sp 1

Free Software Foundation @*

51 Franklin Street, Fifth Floor @*

Boston, MA  02110-1301 USA @*

Phone: +1-617-542-5942 @*

Fax: +1-617-542-2652 @*

Email: @email{gnu@@gnu.org} @*

URL: @uref{http://www.gnu.org/} @*

@c ISBN x-xxxxxx-xx-x @*

@sp 2

@insertcopying

@end ifnotdocbook

@end titlepage

@iftex

@headings off

@evenheading @thispage@ @ @ @strong{@value{TITLE}} @| @|

@oddheading  @| @| @strong{@thischapter}@ @ @ @thispage

@end iftex

@ifnottex

@ifnotxml

@ifnotdocbook

@node Top

@top General Introduction

@c Preface node should come right after the Top

@c node, in `unnumbered' sections, then the first chapter.

This file describes how to participate in software development for

@uref{http://www.gnu.org/software/gawk, GNU Awk (@command{gawk})}.

@insertcopying

@end ifnotdocbook

@end ifnotxml

@end ifnottex

@menu

* Preface::                           Some introductory remarks.

* Contributing::                      How to contribute to @command{gawk}

                                      development.

* Using Git::                         Getting started with Git.

* Configuring git::                   Configuring Git.

* Development without commit access:: How to work without commit access.

* Development with commit access::    How to work with commit access.

* General practices::                 How things should usually be done.

* Repo Maintenance::                  Tips for keeping your repo clean.

* Development Stuff::                 Things you need to know to be a

                                      @command{gawk} developer.

* Cheat Sheet::                       Git command summary.

* Resources::                         Some further resources.

* TODO::                              Stuff still to do.

* Index::                             The index.

@detailmenu

* This Manual::                     How to use this manual.

* Conventions::                     Typographical Conventions.

* Acknowledgments::                 Acknowledgments.

* Reviewers::                       A note to reviewers.

* Push Pull::                       The push/pull software development model.

* Repo Copies::                     What it means to have a copy of a repo.

* Local Branches::                  How to best use local branches.

* Branches are state::              Branches represent development state.

* Repo State::                      The different branch types in the repo.

* Local State::                     Managing local branches.

* Remotes::                         What a ``remote'' is.

* Cloning::                         Cloning the repo the first time.

* Switching Branches::              Moving from one branch to another.

* Starting A New Branch::           Starting a new branch for development.

* Undoing a change::                Throwing away changes.

* Updating::                        Keeping in sync with the upstream repo.

* Rebasing::                        Rebasing A Local Branch.

* Merge Conflicts::                 Dealing With Merge Conflicts.

* Submitting Changes::              How to submit your changes.

* Removing Branches::               Getting rid of unneeded branches.

* Points to remember::              Things you need to keep in mind.

* Initial setup::                   Getting started with commit access.

* ssh clone::                       Cloning using an @samp{ssh://} URL.

* Developing patches::              Developing patches.

* Developing new features::         Developing new features.

* Developing fixes::                Developing fixes.

* Coding style::                    Where to read up on the coding style.

* Doing paperwork::                 Legal stuff in order to contribute.

* Tools::                           Tools to have on your system for

                                    development.

* GNU Tools::                       The GNU Autotools.

* Compilers::                       A discussion of compilers that can be

                                    used.

* Debugging::                       Compiling for debugging.

@end detailmenu

@end menu

@c @summarycontents

@contents

@node Preface

@unnumbered Preface

@c I saw a comment somewhere that the preface should describe the book itself,

@c and the introduction should describe what the book covers.

This @value{DOCUMENT} describes how to participate in development

of GNU Awk (@command{gawk}).  GNU Awk is a Free Software project

belonging to the Free Software Foundation's GNU project.

@menu

* Intended Audience::           Who should read this manual.

* This Manual::                 How to use this manual.

* Conventions::                 Typographical Conventions.

* Acknowledgments::             Acknowledgments.

* Reviewers::                   A note to reviewers.

@end menu

@node Intended Audience

@unnumberedsec Intended Audience

This @value{DOCUMENT} is aimed at software developers who wish

to participate in @command{gawk} development.

You should be comfortable working with traditional Unix-style

command-line tools, and with the C language and standard library facilities.

You should also have some prior experience using distributed

source code control systems, such as the Concurrent Versions

System (CVS) or Subversion (SVN).  Experience with a more modern

system such as Mercurial or Git will be even more helpful.

@cindex Git Project

The @value{DOCUMENT} focuses on participation in the project (that is,

how to work most effectively if you wish to contribute to it) and

also describes how to make use of the @uref{http://git-scm.org, Git}

distributed source code management system for @command{gawk} development.

@node This Manual

@unnumberedsec Using This Book

This @value{DOCUMENT} has the following chapters and appendices:

@itemize @bullet

@item

@ref{Contributing} describes how to start contributing to

the @command{gawk} project.

@item

@ref{Using Git} introduces the Git distributed source code

management system.

@item

@ref{Configuring git} describes some initial set-up you need to do

before using Git seriously.

@item

@ref{Development without commit access} gets into the meat of the

development workflow, describing how to work if you don't have

commit access to the Savannah repository.

@item

@ref{Development with commit access} continues the discussion,

covering what's different when you can commit directly to the

Savannah repository.

@item

@ref{General practices} describes general development

practices used by the @command{gawk} development team.

@item

@ref{Repo Maintenance} presents several different things

you need to know about to keep your repository in good shape.

@item

@ref{Development Stuff} describes some important points you

should be familiar with in order to participate in @command{gawk}

development and presents some tools that may make your work easier.

@item

@ref{Cheat Sheet} provides a short ``cheat sheet'' summarizing

all the Git commands referenced in this @value{DOCUMENT}.

@item

@ref{Resources} provides a few pointers to Internet

resources for learning more about Git.

@end itemize

@node Conventions

@unnumberedsec Typographical Conventions

@cindex Texinfo

This @value{DOCUMENT} is written in @uref{http://www.gnu.org/software/texinfo/, Texinfo},

the GNU documentation formatting language.

A single Texinfo source file is used to produce both the printed and online

versions of the documentation.

@ifnotinfo

Because of this, the typographical conventions

are slightly different than in other books you may have read.

@end ifnotinfo

@ifinfo

This @value{SECTION} briefly documents the typographical conventions used in Texinfo.

@end ifinfo

Examples you would type at the command line are preceded by the common

shell primary and secondary prompts, @samp{$} and @samp{>}.

Input that you type is shown @kbd{like this}.

Output from the command is preceded by the glyph ``@print{}''.

This typically represents the command's standard output.

Error messages and other output on the command's standard error are preceded

by the glyph ``@error{}''.  For example:

@example

$ @kbd{echo hi on stdout}

@print{} hi on stdout

$ @kbd{echo hello on stderr 1>&2}

@error{} hello on stderr

@end example

@ifnotinfo

In the text, almost anything related to programming, such as command

names, variable and function names, and string, numeric and regexp

constants appear in @code{this font}.  Code fragments appear in the same

font and quoted, @samp{like this}.  Things that are replaced by the

user or programmer appear in @var{this font}.  Options look like this:

@option{-f}.  File names are indicated like this: @file{/path/to/ourfile}.

Some things are emphasized @emph{like this}, and if a point needs to be

made strongly, it is done @strong{like this}.  The first occurrence of

a new term is usually its @dfn{definition} and appears in the same font

as the previous occurrence of ``definition'' in this sentence.

@end ifnotinfo

Characters that you type at the keyboard look @kbd{like this}.  In particular,

there are special characters called ``control characters.''  These are

characters that you type by holding down both the @kbd{CONTROL} key and

another key, at the same time.  For example, a @kbd{Ctrl-d} is typed

by first pressing and holding the @kbd{CONTROL} key, next

pressing the @kbd{d} key, and finally releasing both keys.

@quotation NOTE

Notes of interest look like this.

@end quotation

@quotation CAUTION

Cautionary or warning notes look like this.

@end quotation

@node Acknowledgments

@unnumberedsec Acknowledgments

@cindex Kahrs, J@"urgen

Thanks to J@"urgen Kahrs for his initial efforts to write a document like this.

Although his prose has not survived, his material was helpful in preparing

this @value{DOCUMENT}.

@cindex Bernat, Yehezkel

Thanks to Yehezkel Bernat for reviewing this document and

in general for his good intentions.

@strong{FIXME:} YOUR NAME HERE...

@node Reviewers

@unnumberedsec Notes to Reviewers

Please let me know if anything is missing, or unclear.

Real errors with respect Git commands and usage are

very important as well.

Spelling errors and typo fixes welcome, but not as important.

@node Contributing

@chapter How to Start Contributing

@command{gawk} development is distributed.  It's done using electronic

mail (@dfn{email}) and via branches in the Git repository (or @dfn{repo})

on @uref{http://savannah.gnu.org, Savannah}, the GNU

project's source code management site.

In this @value{CHAPTER} we use some Git terminology.  If you're not at

all familiar with Git, then skim this @value{CHAPTER} and come back

after reading the rest of the @value{DOCUMENT}.

@command{gawk} is similar to many other Free Software projects.  To begin

contributing, simply start!  Take a look at the @file{TODO} file in the

distribution, see if there is something of interest to you, and ask on

the @email{bug-gawk@@gnu.org} mailing list if anyone else is working

on it.  If not, then go for it!  (@xref{Development Stuff} for a discussion of some

of the technical things you'll need to do.  Here we describe the process

in general.)

Your contribution can be almost anything that is relevant for

@command{gawk}, such as code fixes, documentation fixes, and/or new

features.

@quotation NOTE

If possible, new features should be done using @command{gawk}'s extension

mechanism.  If you want to add a user-visible language change to the

@command{gawk} core, you're going to have to convince the maintainer

and the other developers that it's really worthwhile to do so.

Changes that improve performance or portability, or that fix bugs,

or that enable more things in extensions,

will require less convincing, of course.

@end quotation

As you complete a task, submit patches for review to the

@email{bug-gawk@@gnu.org} mailing list, where you'll be given feedback

about your work.  Once your changes are acceptable, the maintainer will

commit them to the Git repository.

Over time, as the maintainer and development team gain confidence in your

ability to contribute, you may be asked to join the private @command{gawk}

developers' mailing list, and/or be granted commit access to the Git

repository on Savannah.  This has happened to more than one person who

just ``came out of the woodwork.''

Until that happens, or if you don't want to join the list, you should

continue to work with private branches and submission of patches to the

mailing list.

Once you have commit access, if you want to make a major change or add a

major feature, where the patch(es) would be very large, it has become the

practice to create a separate branch, based off of @code{master}, to host

the feature.  This way the maintainer can review it, and you can continue

to improve it, until it's ready for integration into @code{master}.

@cindex GitHub

@quotation NOTE

Because of the GNU project's requirements for signed paperwork for

contributions, the @command{gawk} project will @strong{not} work

with pull requests from @uref{http://github.com, GitHub} or any other

Git-based software hosting service.  You must submit patches to the

mailing list, and be willing to sign paperwork for large patches

(@pxref{Doing paperwork}).

@end quotation

The @email{bug-gawk@@gnu.org} mailing list is not private.  Anyone may

send mail to it, and anyone may subscribe to it.  To subscribe,

go to the list's @uref{https://lists.gnu.org/mailman/listinfo/bug-gawk,

web page} and follow the instructions there.  If you plan to be involved

long-term with @command{gawk} development, then you probably should

subscribe to the list.

@node Using Git

@chapter Using Git

This chapter provides an introduction to using Git.  Our point is

@emph{not} to rave about how wonderful Git is, nor to go into painful

detail about how it works.  Rather we want to give you enough background

to understand how to use Git effectively for bug fix and feature

development and to interact (``play nicely'') with the development team.

@menu

* Push Pull::                   The push/pull software development model.

* Repo Copies::                 What it means to have a copy of a repo.

* Local Branches::              How to best use local branches.

* Branches are state::          Branches represent development state.

@end menu

@node Push Pull

@section The ``Push/Pull'' Model of Software Development

Git is a powerful, distributed source code management system.  However,

the way it's used for @command{gawk} development purposely does not take

advantage of all its features.

Instead, the model is rather simple, and in many ways much like more

traditional distributed systems such as the @uref{http://www.nongnu.org/cvs,

Concurrent Versions System} (CVS) or

@uref{http://subversion.apache.org, Subversion} (SVN).

The central idea can be termed ``push/pull.'' You @emph{pull} updates down from

the central repository to your local copy, and if you have commit rights,

you @emph{push} your changes or updates up to the central repository.

Other developers work this way; pushing their changes up to the central

repository and pulling your changes down into theirs.

Where Git does stand out is in its management of multiple branches of

development.  Git makes it very easy to set up a separate branch for

use in fixing a bug or developing a feature.  You can then easily keep

that branch up to date with respect to the main development branch(es),

and eventually merge the changes from your branch into the main branch.

Almost always Git does these merges for you without problem.  When there

is a problem (a @dfn{merge conflict}), usually it is very easy for you

to @dfn{resolve} them and then complete the merge.  We talk about this

in more detail later (@pxref{Merge Conflicts}).

@node Repo Copies

@section How Git Stores Branches and Their Copies

So how does Git work?@footnote{The following description is greatly

simplified.}

A repository consists of a collection of @dfn{branches}.  Each branch

represents the history of a collection of files and directories (a file

@dfn{tree}).  Each combined set of changes to this collection (files and