Skip site navigation (1)Skip section navigation (2)
Date:      Wed, 03 Jun 2020 17:26:08 -0600
From:      Brandon Helsley <brandon.helsley@hotmail.com>
To:        Polytropon <freebsd@edvax.de>
Cc:        freebsd-questions@freebsd.org
Subject:   Re: Mininal skills
Message-ID:  <CY4PR19MB0104C290121BF756D57B2DDBF9880@CY4PR19MB0104.namprd19.prod.outlook.com>
In-Reply-To: <20200604005859.ca438474.freebsd@edvax.de>
References:  <CY4PR19MB0104A2C03F4D66A1DA251A23F9880@CY4PR19MB0104.namprd19.prod.outlook.com> <20200604005859.ca438474.freebsd@edvax.de>

next in thread | previous in thread | raw e-mail | index | archive | help
By "without any skills" I mean that I'm new to computers and am not even fa=
miliar with the terminology thrown around in the FreeBSD community=2E=20

I've never heard of this documentation updating, I'd love to learn more=2E=
 Who should I be talking to or where should I be referring to so I can lear=
n=2E=2E=2E=20

I sent a PR from some account I created about a bug in the loading of the =
kernel modules for bhyve=2E I'm starting to think I didn't quite format it =
correctly or rather communicate the issue correctly=2E I heard that filing =
PR's is also a good starting point to get involved=2E Could someone help me=
 find the documentation that explains how to file a PR or update documentat=
ion=2E

Brandon

On June 3, 2020 4:58:59 PM MDT, Polytropon <freebsd@edvax=2Ede> wrote:
>On Wed, 03 Jun 2020 15:54:28 -0600, Brandon Helsley wrote:
>> I've searched around FreeBSD documentation and have found
>> that most of the contributions require at least minimal
>> programming skills=2E My question is whether or not there
>> is anything I can contribute or maintain for freebsd
>> without any skills=2E
>
>What does "without any skills" imply for a human being?
>If you cannot program, then there are other aspects of
>FreeBSD you can contribute to, for example documentation=2E
>You can read and write - those _are_ skills (even though
>in our "modern world" there are often undervalued)=2E
>
>
>
>> What direction should I take my education if I wish to
>> be able to maintain a port=2E
>
>That primarily depends on the port=2E Just as an example,
>the FreeBSD documentation is also a port=2E The toolset
>to use it is already present=2E So if you wanted to become
>a documentation contributor, you would have to learn how
>to _use_ those tools, not how they work interally=2E
>
>
>
>> Is c++ programming required?
>
>Depends on the port=2E Knowing C++ is not useful when the
>port uses C or assembly (like a device driver would), or
>Python, or Lua=2E To become a port maintainer, you should
>be able to use the programming language(s) the port uses=2E
>So when a patch is needed, you will often have to use
>the required programming language(s); sometimes upstream
>will provide patches for FreeBSD, sometimes they won't,
>so you have to find out for yourself what to do to make
>the port work again, for example if a security fix is
>needed, or if an enhancement in functionality requires
>a specific action for FreeBSD=2E
>
>
>
>> What else is required?
>
>Primarily, learning by doing=2E :-)
>
>You should first make yourself familiar with how the whole
>ports thing works=2E The FreeBSD Porter's Handbook is a good
>resource for that=2E Of course you should be able to use
>FreeBSD as an operating system=2E Furthermore, you should
>be able to use the required programming language(s) of
>the port in question=2E Additionally you should probably be
>able to deal with the FreeBSD bug tracking system and have
>the required communication skills to talk to upstream, if
>needed=2E If it hasn't become clear yet, you should of course
>learn how to use the ports infrastructure, working copy
>checkout, creation of patches, building and testing, and
>so on=2E Yes, this sounds quite trivial, but it is often
>neccessary to be able to do all this as a port maintainer=2E
>
>While reading the porter's handbook, it will become clear
>to you if this is a task you want to learn more about, and
>acquire more skills while (!) you do so=2E You will recognize
>which tools you are already familiar with, and which ones
>you'll have to learn=2E Without any doubt, you will grow your
>skillset already with those first steps=2E
>
>
>
>--=20
>Polytropon
>Magdeburg, Germany
>Happy FreeBSD user since 4=2E0
>Andra moi ennepe, Mousa, =2E=2E=2E

--=20
Sent from my Android device with K-9 Mail=2E Please excuse my brevity=2E
From owner-freebsd-questions@freebsd.org  Thu Jun  4 00:00:56 2020
Return-Path: <owner-freebsd-questions@freebsd.org>
Delivered-To: freebsd-questions@mailman.nyi.freebsd.org
Received: from mx1.freebsd.org (mx1.freebsd.org [IPv6:2610:1c1:1:606c::19:1])
 by mailman.nyi.freebsd.org (Postfix) with ESMTP id 8A0352F80BB
 for <freebsd-questions@mailman.nyi.freebsd.org>;
 Thu,  4 Jun 2020 00:00:56 +0000 (UTC)
 (envelope-from freebsd@edvax.de)
Received: from mout.kundenserver.de (mout.kundenserver.de [217.72.192.73])
 (using TLSv1.3 with cipher TLS_AES_256_GCM_SHA384 (256/256 bits)
 key-exchange ECDHE (P-256) server-signature RSA-PSS (4096 bits) server-digest
 SHA256 client-signature RSA-PSS (2048 bits) client-digest SHA256)
 (Client CN "mout.kundenserver.de",
 Issuer "TeleSec ServerPass Class 2 CA" (verified OK))
 by mx1.freebsd.org (Postfix) with ESMTPS id 49cmBv3VJ5z45ft
 for <freebsd-questions@freebsd.org>; Thu,  4 Jun 2020 00:00:55 +0000 (UTC)
 (envelope-from freebsd@edvax.de)
Received: from r56.edvax.de ([94.222.2.120]) by mrelayeu.kundenserver.de
 (mreue106 [212.227.15.183]) with ESMTPA (Nemesis) id
 1M5g68-1jaYll3mA6-007BBr; Thu, 04 Jun 2020 02:00:52 +0200
Date: Thu, 4 Jun 2020 02:00:51 +0200
From: Polytropon <freebsd@edvax.de>
To: Brandon Helsley <brandon.helsley@hotmail.com>
Cc: freebsd-questions@freebsd.org
Subject: Re: Mininal skills
Message-Id: <20200604020051.0c02472d.freebsd@edvax.de>
In-Reply-To: <CY4PR19MB0104C290121BF756D57B2DDBF9880@CY4PR19MB0104.namprd19.prod.outlook.com>
References: <CY4PR19MB0104A2C03F4D66A1DA251A23F9880@CY4PR19MB0104.namprd19.prod.outlook.com>
 <20200604005859.ca438474.freebsd@edvax.de>
 <CY4PR19MB0104C290121BF756D57B2DDBF9880@CY4PR19MB0104.namprd19.prod.outlook.com>
Reply-To: Polytropon <freebsd@edvax.de>
Organization: EDVAX
X-Mailer: Sylpheed 3.1.1 (GTK+ 2.24.5; i386-portbld-freebsd8.2)
Mime-Version: 1.0
Content-Type: text/plain; charset=US-ASCII
Content-Transfer-Encoding: 7bit
X-Provags-ID: V03:K1:LsehX8s+5roKbl45W9hcDuwTZQIBpJAKgicE8uqMVWOqLD2xWgb
 ertIoyw8YYi8o/PbD5RBfaa8COyLLkaep7tevnCdqUMc6l5IPtCq1KPbXD07DBb4kSBEnjh
 v02MO0nwHBRPIAHuiYQUhK5BWPFYwOY9baM6Ch7bug4vTUcAtJ7wnF7RlbH57aKTqnF062e
 skgLS2YQJi7Ryw+1Rr0Bw==
X-Spam-Flag: NO
X-UI-Out-Filterresults: notjunk:1;V03:K0:O4lxMaY2ZtU=:mv/8fRruTst4043tM+YW7W
 cXtz7Cxv0r7VFGoyxs+JtauxJWUmnxp9qu2poYZBzKcZlluXUJFovszQQHu9LIOMu4C02wCi2
 Em54IqSt2o2LKyJG7dEvlq31V4dQnh/NJfqJh3Fp4RHv4GVlx4379sSzBU61aCISy3AYQD/Ko
 zQ1sJ+0H9RwscaSCIGwApELG2nq4ISoY872sIbo0Rm/CsKOily6na5UEFweDfPtBNa5omg38v
 eD6Xet4PwjUweF+yfyDAn6Fuaeqb+KV/SN2jJrUeaEukhgO3mgeHkEiMiJ5X9LZ4RBlXisgDE
 zgnu0efYTDDZKS6HD0J/ry+QJ5FPmBkEbp1l5k95cj67SKjvW8kbtmMhOYtCEGlVBwhxPng/p
 97QUtFlsdQmH6/JNC4BCNGOmt6T5RJTPBZtmkCoJkJcOySVsg52XpQCR8GqjEc+hPw3JlvEVi
 nSOyqChSQXiPI5rRoZ9QL4bVZLyx6xfJpL4VCwtAU2Fj+pzs+EBiX7DtDHtCW/1Ogiu3g7TUI
 S749JJA8mkGG+ScRbCs0gmqcAm4hadhXIW/bnLPr1NEps12eGjpBLxL1Lh7NIuhuDgWiqD/j5
 yAb8fz0FRldMkhq7XicsvF0kyW99eTWXasAGtASFGsaoRe+WQtaquskvxzfG6i+crsTRY3z5X
 qNQVaoCRKq9urNIrnyH1XSyZS8s1h+ELMZtFYHjvQ46w4WPkfRIFJQgtoEVx6dguDvdp5er21
 Sl5J6qDVqIFAZsAOZtgbTooAdKEoNEHjIJ+MMBG4+QNOCpAPUgXayaaY2r82jTK18XzELwP5Q
 MURlmp46fAWUA7oeNpQWsYHg1KRc+8Mm8CPe8OKPFGaG2K3C71CST5sb8bBsu1HT+kNEqaMx4
 gXtAyBHci2uG2M+rGRjw==
X-Rspamd-Queue-Id: 49cmBv3VJ5z45ft
X-Spamd-Bar: ++
Authentication-Results: mx1.freebsd.org; dkim=none; dmarc=none;
 spf=none (mx1.freebsd.org: domain of freebsd@edvax.de has no SPF policy when
 checking 217.72.192.73) smtp.mailfrom=freebsd@edvax.de
X-Spamd-Result: default: False [2.15 / 15.00];
 HAS_REPLYTO(0.00)[freebsd@edvax.de];
 RCVD_VIA_SMTP_AUTH(0.00)[]; TO_DN_SOME(0.00)[];
 MV_CASE(0.50)[]; HAS_ORG_HEADER(0.00)[];
 NEURAL_HAM_SHORT(-0.05)[-0.049]; RCPT_COUNT_TWO(0.00)[2];
 FREEMAIL_TO(0.00)[hotmail.com];
 RECEIVED_SPAMHAUS_PBL(0.00)[94.222.2.120:received];
 RCVD_TLS_LAST(0.00)[]; R_DKIM_NA(0.00)[];
 FROM_EQ_ENVFROM(0.00)[]; MIME_TRACE(0.00)[0:+];
 ASN(0.00)[asn:8560, ipnet:217.72.192.0/20, country:DE];
 ARC_NA(0.00)[]; NEURAL_HAM_MEDIUM(-0.72)[-0.722];
 REPLYTO_EQ_FROM(0.00)[]; FROM_HAS_DN(0.00)[];
 MIME_GOOD(-0.10)[text/plain]; DMARC_NA(0.00)[edvax.de];
 AUTH_NA(1.00)[]; TO_MATCH_ENVRCPT_SOME(0.00)[];
 NEURAL_SPAM_LONG(0.52)[0.523]; MID_CONTAINS_FROM(1.00)[];
 RCVD_IN_DNSWL_NONE(0.00)[217.72.192.73:from];
 R_SPF_NA(0.00)[no SPF record];
 RWL_MAILSPIKE_POSSIBLE(0.00)[217.72.192.73:from];
 RCVD_COUNT_TWO(0.00)[2]
X-BeenThere: freebsd-questions@freebsd.org
X-Mailman-Version: 2.1.33
Precedence: list
List-Id: User questions <freebsd-questions.freebsd.org>
List-Unsubscribe: <https://lists.freebsd.org/mailman/options/freebsd-questions>, 
 <mailto:freebsd-questions-request@freebsd.org?subject=unsubscribe>
List-Archive: <http://lists.freebsd.org/pipermail/freebsd-questions/>;
List-Post: <mailto:freebsd-questions@freebsd.org>
List-Help: <mailto:freebsd-questions-request@freebsd.org?subject=help>
List-Subscribe: <https://lists.freebsd.org/mailman/listinfo/freebsd-questions>, 
 <mailto:freebsd-questions-request@freebsd.org?subject=subscribe>
X-List-Received-Date: Thu, 04 Jun 2020 00:00:56 -0000

On Wed, 03 Jun 2020 17:26:08 -0600, Brandon Helsley wrote:
> By "without any skills" I mean that I'm new to computers and
> am not even familiar with the terminology thrown around in
> the FreeBSD community.

That's absolutely no problem. The more you use FreeBSD, the
better you will know the terminology, which is mostly out of
three classes: general computer terminology, UNIX terminology,
FreeBSD-specific terminology. It is important to understand
the meaning of termini technici originating in those classes,
and _what_ exactly to be "eloquent" at depends on the area
of documentation you want to deal with.



> I've never heard of this documentation updating, I'd love to
> learn more. Who should I be talking to or where should I be
> referring to so I can learn... 

The FreeBSD Documentation Project has its own sub-page:

	https://www.freebsd.org/docproj/

Which can be reached from the central documentation site:

	https://www.freebsd.org/docs.html

There is even a dedicated mailing list - freebsd-doc@freebsd.org
which is used to discuss documentation-specific issues. For use
with this mailing lists, as well as all other mailing lists, I
recommend this summary:

	https://www.freebsd.org/doc/en_US.ISO8859-1/articles/mailing-list-faq/

Note that "documentation" doesn't just refer to manual pages;
it also includes project web pages, books and FAQ, publications,
maybe even the Wiki and other material.

Note that the handbook you can access with your web browser
is, technically, nothing else than the same handbook you can
patch and rebuild on your local machine, be it HTML or PDF as
the target: Those results are generated from the same source.

So for example, if you wanted to contribute to the handbook,
you'd obtain the latest version of it, and the required tools,
make your changes, test them locally, then create patches and
commit them (or send them in to be commited by someone else).

Instead, if you wanted to update OS manual pages, you'd obtain
the system's sources, modify and test the man page source file,
create a patch, and send it in.

Your primary tool here is a text editor. Depending on your
individual preference, that could be vi, vim, emacs, mcedit,
joe, something X-based, whatever fits your needs. It does not
even matter. Reading "man diff" and "man patch" is probably
also a significant advantage. There are other tools that might
get involved.

Allow me to drop a few relevant articles:

  1.	FreeBSD Documentation Project: Submitting documentation
	I have written some documentation. How do I submit it?

	https://www.freebsd.org/docproj/submitting.html

  2.	FreeBSD Documentation Project Primer for New Contributors

	https://www.freebsd.org/doc/en_US.ISO8859-1/books/fdp-primer/index.html

  3.	Committer's Guide

	https://www.freebsd.org/doc/en_US.ISO8859-1/articles/committers-guide/index.html

A bit more general:

	Contributing to FreeBSD

	https://www.freebsd.org/doc/en_US.ISO8859-1/articles/contributing/index.html

As I mentioned, there is also a mailing list where you can
ask questions specifically related to documentation (and
this list, freebsd-questions@, is absolutely appropritate
for general questions such as this one).



> I sent a PR from some account I created about a bug in the
> loading of the kernel modules for bhyve. I'm starting to think
> I didn't quite format it correctly or rather communicate the
> issue correctly. I heard that filing PR's is also a good
> starting point to get involved. Could someone help me find
> the documentation that explains how to file a PR or update
> documentation.

The most convenient way to send a bug report is to use the
following page:

	https://www.freebsd.org/support/bugreports.html

You can even find a good outline of _how_ to file a bug report:

	https://www.freebsd.org/doc/en_US.ISO8859-1/articles/problem-reports/

Older FreeBSD versions included a "send-pr" program. :-)




-- 
Polytropon
Magdeburg, Germany
Happy FreeBSD user since 4.0
Andra moi ennepe, Mousa, ...



Want to link to this message? Use this URL: <https://mail-archive.FreeBSD.org/cgi/mid.cgi?CY4PR19MB0104C290121BF756D57B2DDBF9880>