===== 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 =====

  * Optional: Create a dedicated email address. Contributor/maintainer emails are public, and you can expect some spam [[https://accounts.google.com/signup|Gmail]] is good)
  * Create a [[/Bugzilla]] account.
    * Set your Full Name in Bugzilla User Preferences (for credit in commit logs!)
  * Set ''%%DEVELOPER=yes%%'' in ''%%/etc/make.conf%%'', which enables extra 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]] (See Also: [[VladimirKrstulja/Guides/Poudriere|Poudriere]])

For **bonus** points:

  * Optional but highly recommended: [[/GitHub|GitHub]] or similar account for managing a ports tree. Allows for easy review if you need help, and others to contribute.

===== 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 (Bugzilla)]]
  * [[http://portscout.freebsd.org/|FreeBSD Portscout]] (shows ports with outdated / new versions)
  * [[https://freshports.org/|FreshPorts]]

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

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

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

This is a basic process for making changes to one port. If you plan to do longer-term ports work, or across multiple ports, we suggest cloning
an entire ports tree with git, so you have all of those tools and features available to you (like branching, stashing, etc).

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

  * Setup your ''%%~username/.porttools%%'' configuration (Read ''%%man 5 porttools%%'')

  - Copy the ''%%category/port%%'' you want to modify from ''%%/usr/ports%%'' into a 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

----

{{tag>Ports}}
{{tag>Contributing}}
{{tag>HowTo}}