====== FreeBSD Ports: New Contributors 101 ======

First up, **thank you** for deciding to dedicate your time and effort to the %%FreeBSD%% community and to make things better.

This guide is designed to be lightweight, get you ramped up //quickly//, and save you time and effort. Is it **not** exhaustive.

===== Get Ready =====

  * Create a dedicated Email address. But expect spam ([[https://accounts.google.com/signup|Gmail]] is good).
  * Create a [[https://bugs.freebsd.org/bugzilla/|FreeBSD Bugzilla]] account.
    * Set your Full Name (for credit in commit logs).
  * Set ''%%DEVELOPER=yes%%'' in [[https://man.freebsd.org/make.conf|/etc/make.conf]] (turns on lots of QA/error/sanity checks).

===== Get The Tools =====

At a **minimum**:

  * Porttools   [[https://www.freshports.org/ports-mgmt/porttools/|ports-mgmt/porttools]] (installs portlint)
  * Portlint    [[https://www.freshports.org/ports-mgmt/portlint/|ports-mgmt/portlint]]
  * Poudriere   [[https://www.freshports.org/ports-mgmt/poudriere/|ports-mgmt/poudriere]]

For **bonus** points:

  * %%GitLab%%, Bitbucket or %%GitHub%% account for managing a ports tree
  * Mercurial or Git

===== Your Resources =====

  * [[https://www.freebsd.org/doc/en_US.ISO8859-1/books/porters-handbook/book.html|FreeBSD Porters Handbook]]
  * [[https://bugs.freebsd.org/bugzilla/|FreeBSD Issue Tracker]]
  * [[http://portscout.freebsd.org/|FreeBSD Portscout]]
  * [[https://freshports.org/|FreshPorts]]
  * [[http://portsmon.freebsd.org/|FreeBSD Ports Monitor (portsmon)]]
    * It's being down for maintenance at the moment (2018.04.28)

===== Your Support Network =====

  * EFNet IRC:    #bsdports, #freebsd-bugbusters
  * Libera.Chat IRC: #freebsd-ports, #freebsd (You'll need to register your nickname: /ns help register)
  * Twitter:      [[https://twitter.com/FreeBSDHelp|@FreeBSDHelp]]

===== The Basic Process =====

Create a place where you'll keep your local ports, ''%%~username/ports%%'' is fine.

Setup your ''%%~username/.porttools%%'' configuration (read [[https://man.freebsd.org/cgi/man.cgi?query=porttools&sektion=5&manpath=freebsd-ports|porttools(5)]]).

  - Copy the category/port you want to modify from /usr/ports into your local tree
  - Make your changes
  - Test your changes (portlint, poudriere, unit tests, etc)
  - Submit your changes

Here it is in action

<code>
cp -Rp /usr/ports/category/portname ~username/ports/category
# make some changes
port test
# fix reported issues
port test
port diff
</code>

Looks good!

<code>
port diff > patch.diff
</code>

Create new Bugzilla issue.

Attach ''%%patch.diff%%'' to issue.

===== Protips and Magic Incantations =====

The following work in port directories (ie: category/port)

  * ''%%make makesum%%'' When you change what files a port downloads (updates distinfo file)

  * ''%%make makepatch%%'' Automatically creates patches in files/ using filename/filename.orig pairs)

  * ''%%make -V VARIABLE%%'' Check the value of a make VARIABLE

----

===== Other resources =====

  * [[MateuszPiotrowski/Ports/Workshops|Notes for workshops introducing to porting on FreeBSD]]
  * [[https://bitbucket.org/if0/freebsd-kanboard/src/2c45f1e512042f88a4a7242862b314cc3ee86c7c/port_maintain.md?at=default&fileviewer=file-view-default|How to maintain a port 101 by if0 (bitbucket.org/if0/freebsd-kanboard/)]]

----

{{tag>HowTo Ports}}

Based on //[[https://bitbucket.org/koobs/ports/overview|FreeBSD Ports: New Contributors 101]]// by [[/KubilayKocak|KubilayKocak]]