Skip to content

Home

Jump to bottom
Walter G Davies - ASCCON edited this page Mar 27, 2024 · 4 revisions

Welcome to the DStat wiki!

SDLC Process

A working binary of DStat may be built from the top-level of a complete, shallow-clone repository, by running make all.

Make Targets

Additional targets for Make include:

  • version: Update the version strings in lib/version.h and man1/dstat.1md files from the current Git Tag.
  • manpage: Build a manpage from the source Markdown file (man1/dstat.1.md). Note: Requires pandoc(1).
  • debug: Build a DStat binary executable that features additional trace output.
  • clean: Remove the DStat binary.
  • mrproper: Removes all files that result from any of the preceding build processes.

Issue/Build/Test/Graduation Cycle

The general process of filing an Issue, resolving the Issue in code, and graduating a new version (the Cycle) is as follows.

File or Select an Issue

To file a new Issue:

  • Observe a problem or deficiency of the program (e.g, documented feature not working in accordance with the documentation or a useful feature that should be implemented) and file a new Issue against it.
    • Issue title should be succinct, e.g: "CVS format does not include the X column" or "Directory recursion should be done in parallel".
    • The Description should identify the discrepancy between expected and actual behaviour. Sample output can be very helpful.
    • The Issue must (as much as possible) be atomic, i.e: One issue is identified that can be addressed as a unit. A single Issue must not be complex, e.g: "" or overly vague, e.g: "Program runs too slow". The former example could be better separated into at least two Issues, the latter should instead describe a specific performance enhancement or situation under which performance suffers.
    • If known, enter an Assignee(s), appropriate Label(s) (e.g: Bug, Enhancement, Documentation, &c), Project(s), and Milestone(s). Do not create a new Branch (or assign a Branch) to the Issue unless you are actively working on the Issue (in which case, Assignees should include yourself).

To select an Issue:

  • Find an Issue that fits your interest and expertise.
  • Ensure that the Issue is Open, not assigned, and/or no Development branch is shown.
    • If the Issue is already assigned and/or has a Development branch already listed, check with the Assignee(s) and/or the Project Owner (@ASCCON) prior to contributing any work.
  • Add yourself as an Assignee and ensure at least one Label has been applied. If you believe any Label(s) are inappropriate or inadequate, feel free to add to or modify the Labels assigned to the Issue. Please do not modify the Labels, themselves! If a Label does not exist, please add it rather than modifying an existing Label. If you don't know what any of this means, please contact @ASCCON for guidance.
  • Ensure the Project(s) and/or Milestone(s) tabs are populated appropriately.
  • Finally, create a new Development branch.
    • From the GitHub GUI, select "Create a branch". A dialogue box appears; for the "Branch name", the default is usually fine. In any case, the format of the Branch name must be "N-issue-title", where "N" is the Issue number. Please try to keep titles to around 40 or fewer characters so they are less obnoxious to type when switching between or listing branches. If some editing of the title is needed to shorten it, ensure the preceding number is maintained, the title still reflects the nature of the Issue, and there are no space or special characters (other than "-" to separate words).
    • Under "What's next?", select "Checkout locally" and then select the "Create branch" button. A new dialogue box will appear with the Git commands that may be copied to update your local repo with the new development Branch.

Edit the Code

The code and documentation demonstrate a consistent format which should describe how additional efforts should be made.

Commit the Code

Please use Smart Commits when making a final commit. Intermediate commits must include at least one line of explanatory text, e.g:

example$ git commit -S -am 'Testing circular list performance enhancement.'

Note that commit comments, like code comments, may be terse as long as they are reasonably clear, contextually obvious, and reasonably well-formed English-language sentences. For final commits that are expected to spawn a Pull Request, please use Smart Commits such as this example:

example$ git commit -S -am '#close X-issue-title
>  #comment
>  * Corrected the order of operations for variable population in the `doIt()` function.
>  * Updated the input parameter types on `doIt()`.
>  * Purchased Kennedy\'24 bumper sticker.
> '
[X-issue-title 9625f6b] ...
example$ git push
...

Also note in these exampels that commit signing is encouraged!

Submit Pull Request

Update from main

Once the the Pull Request has been approved, a privileged committer will update the Version string on the main branch:

example$ git tag X.Y.Z-<optional>-<string>
example$ git push --tags
example$ make mrproper version manpage
example$ git commit -S -am 'Updated Version string to X.Y.Z-<optional>-<string>.'
...
example$ git push

Clone this wiki locally