143 lines
5.8 KiB
Markdown
143 lines
5.8 KiB
Markdown
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.
|