Subversion Repositories configs

Easy-RSA 3 Hacking Guide

===

This document is aimed at programmers looking to improve on the existing

codebase.

Compatibility

---

The `easyrsa` code is written in POSIX shell (and any cases where it is not is

considered a bug to be fixed.) The only exceptions are the `local` keyword and

the construct `export FOO=baz`, both well-supported.

As such, modifications to the code should also be POSIX; platform-specific code

should be placed under the `distro/` dir and listed by target platform.

Coding conventions

---

While there aren't strict syntax standards associated with the project, please

follow the existing format and flow when possible; however, specific exceptions

can be made if there is a significant reason or benefit.

Do try to:

  * Keep variables locally-scoped when possible

  * Comment sections of code for readability

  * Use the conventions for prefixes on global variables

  * Set editors for tab stops of 8 spaces

  * Use tabs for code indents; use aligned spaces for console text

Keeping code, docs, and examples in sync

---

Changes that adjust, add, or remove features should have relevant docs, help

output, and examples updated at the same time.

Release versioning

---

A point-release bump (eg: 3.0 to 3.1) is required when the frontend interface

changes in a non-backwards compatible way. Always assume someone has an

automated process that relies on the current functionality for official

(non-beta, non-rc) releases. A possible exception exists for bugfixes that do

break backwards-compatibility; caution is to be used in such cases.

The addition of a new command may or may not require a point-release depending

on the significance of the feature; the same holds true for additional optional

arguments to commands.

Project layout

---

The project's files are structured as follows:

  * `easyrsa3/` is the primary project code. On Linux/Unix-alikes, all the core

    code and supporting files are stored here.

  * `Licensing/` is for license docs.

  * `build/` is for build information and scripts.

  * `contrib/` is for externally-contributed files, such as useful external

    scripts or interfaces for other systems/languages.

  * `distro/` is for distro-specific supporting files, such as the Windows

    frontend wrappers. Code components that are not platform-neutral should go

    here.

  * `doc/` is for documentation. Much of this is in Markdown format which can be

    easily converted to HTML for easy viewing under Windows.

  * `release-keys/` list current and former KeyIDs used to sign release packages

    (not necessarily git tags) available for download.

  * The top-level dir includes files for basic project info and reference

    appropriate locations for more detail.

As a brief note, it is actually possible to take just the easyrsa3/ dir and end

up with a functional project; the remaining structure includes docs, build prep,

distro-specific wrappers, and contributed files.

Git conventions

---

As of Easy-RSA 3, the following git conventions should be used. These are mostly

useful for people with repo access in order to keep a standard meaning to commit

messages and merge actions.

### Signed-off-by: and related commit message lines

  Committers with push access should ensure a `Signed-off-by:` line exists at

  the end of the commit message with their name on it. This indicates that the

  committer has reviewed the changes to the commit in question and approve of

  the feature and code in question. It also helps verify the code came from an

  acceptable source that won't cause issues with the license.

  This can be automatically added by git using `git commit -s`.

  Additional references can be included as well. If multiple people reviewed the

  change, the committer may add their names in additional `Signed-off-by:`

  lines; do get permission from that person before using their name, however ;)

  The following references may be useful as well:

  * `Signed-off-by:` -- discussed above, indicates review of the commit

  * `Author:` -- references an author of a particular feature, in full or

    significant part

  * `Changes-by:` -- indicates the listed party contributed changes or

    modifications to a feature

  * `Acked-by:` -- indicates review of the feature, code, and/or functional

    correctness

### Merging from external sources (forks, patches, etc)

  Contributions can come in many forms: GitHub "pull requests" from cloned

  repos, references to external repos, patches to the ML, or others. Those won't

  necessary have `Signed-off-by:` lines or may contain less info in the commit

  message than is desirable to explain the changes.

  The committing author to this project should make a merge-commit in this case

  with the appropriate details provided there. If additional code changes are

  necessary, this can be done on a local branch prior to merging back into the

  mainline branch.

  This merge-commit should list involved contributors with `Author:` or similar

  lines as required. The individual commits involved in a merge also retain the

  original committer; regardless, the merge-commit message should give a clear

  indication of what the entire set of commits does as a whole.

### Tagging

  Tags should follow the convention:

    vM.m.p

  where `M` is the major version, `m` is the minor "point-release" version, and

  `p` is the patch-level. Suffixes of `-rc#`, `-beta#`, etc can be added for

  pre-release versions as required.

  Currently tags are taken from the mainline development branch in question. The

  ChangeLog should thus be updated prior to tagging. Tags should also be

  annotated with an appropriate commit message and signed-off. This can be done

  as shown below (don't use `-s` unless you intend to use GPG with git.)

    git tag -a v1.2.3

  Corresponding release downloads can be uploaded to release distribution points

  as required.