From 8e867505fcfed11a32681ce339c2e48c1b762d4d Mon Sep 17 00:00:00 2001 From: Joel Date: Sun, 29 Jan 2023 20:47:46 -0500 Subject: [PATCH] improve project documentation Add several standard open source community documents, as well as improve the existing ones. These changes are intended to make the project more accessible to potential contributors. --- .github/ISSUE_TEMPLATE/bug_report.md | 26 ++++ .github/ISSUE_TEMPLATE/feature_request.md | 20 +++ .github/pull_request_template.md | 6 + CITATION.cff | 2 +- Cargo.lock | 2 +- Cargo.toml | 2 +- README.md | 50 ++++++- docs/CONTRIBUTING.md | 157 ++++++++++++++++++++++ docs/SECURITY.md | 33 +++++ docs/dependencies.md | 6 + docs/roadmap.md | 72 ++++++++++ 11 files changed, 371 insertions(+), 5 deletions(-) create mode 100644 .github/ISSUE_TEMPLATE/bug_report.md create mode 100644 .github/ISSUE_TEMPLATE/feature_request.md create mode 100644 .github/pull_request_template.md create mode 100644 docs/CONTRIBUTING.md create mode 100644 docs/SECURITY.md create mode 100644 docs/dependencies.md create mode 100644 docs/roadmap.md diff --git a/.github/ISSUE_TEMPLATE/bug_report.md b/.github/ISSUE_TEMPLATE/bug_report.md new file mode 100644 index 0000000..6164852 --- /dev/null +++ b/.github/ISSUE_TEMPLATE/bug_report.md @@ -0,0 +1,26 @@ +--- +name: Bug report +about: Create a report to help us fix problems +title: '' +labels: '' +assignees: '' + +--- + +**Describe the bug** +A clear and concise description of what the bug is. + +**To Reproduce** +Steps to reproduce the behavior. Code snippets are preferred, especially if they are easily converted to unit tests that can be used for regression testing. Be sure to include the full output of running the snippet as well. + +**Expected behavior** +A clear and concise description of what you expected to happen with the provided code. + +**Build Environment** +Describe your build environment and any other factors that contribute to the configuration of Stumpless. This should include: + * your operating system + * your compiler (both Rust and the one used to build stumpless-sys) + * any features used + +**Additional context** +Add any other context about the problem here. diff --git a/.github/ISSUE_TEMPLATE/feature_request.md b/.github/ISSUE_TEMPLATE/feature_request.md new file mode 100644 index 0000000..2d98927 --- /dev/null +++ b/.github/ISSUE_TEMPLATE/feature_request.md @@ -0,0 +1,20 @@ +--- +name: Feature request +about: Suggest an idea for stumpless +title: '' +labels: '' +assignees: '' + +--- + +**Is your feature request related to a problem? Please describe.** +A clear and concise description of the problem this feature would solve. + +**Describe the solution you'd like** +A clear and concise description of what you want to happen. + +**Describe alternatives you've considered** +A clear and concise description of any alternative solutions or features you've considered. + +**Additional context** +Add any other context about the feature request here, such as links to other discussions or related bugs. diff --git a/.github/pull_request_template.md b/.github/pull_request_template.md new file mode 100644 index 0000000..69dc15a --- /dev/null +++ b/.github/pull_request_template.md @@ -0,0 +1,6 @@ +Describe the overall purpose of your pull request in a few sentences, keeping +things at a high level. If this request is in response to a particular issue, +include a reference to it here. + +Make sure that your pull request follows the guidelines specified in the +[Guidelines for Contributing](https://github.com/goatshriek/stumpless-logger/blob/latest/docs/CONTRIBUTING.md). diff --git a/CITATION.cff b/CITATION.cff index 53befa2..6187bbc 100644 --- a/CITATION.cff +++ b/CITATION.cff @@ -3,7 +3,7 @@ title: Stumpless CLI and Rust Library type: software license: Apache-2.0 repository-code: "https://github.com/goatshriek/stumpless-logger" -version: 0.1.0 +version: 0.2.0 date-released: 2023-01-28 keywords: - cli diff --git a/Cargo.lock b/Cargo.lock index 0791c9c..e1e4a95 100644 --- a/Cargo.lock +++ b/Cargo.lock @@ -362,7 +362,7 @@ checksum = "73473c0e59e6d5812c5dfe2a064a6444949f089e20eec9a2e5506596494e4623" [[package]] name = "stumpless" -version = "0.1.0" +version = "0.2.0" dependencies = [ "clap", "embed-resource", diff --git a/Cargo.toml b/Cargo.toml index 9da8b36..17ecca9 100644 --- a/Cargo.toml +++ b/Cargo.toml @@ -1,7 +1,7 @@ [package] name = "stumpless" description = "Sends log information to a variety of destinations, local and remote." -version = "0.1.0" +version = "0.2.0" authors = ["Joel Anderson "] edition = "2021" repository = "https://github.com/goasthriek/stumpless-logger/" diff --git a/README.md b/README.md index 24c4a83..1fc21f0 100644 --- a/README.md +++ b/README.md @@ -1,11 +1,16 @@ +**An enhanced command line logging utility.** + +[![crates.io](https://img.shields.io/crates/v/stumpless)](https://crates.io/crates/stumpless) [![Linux Builds](https://github.com/goatshriek/stumpless-logger/actions/workflows/linux.yml/badge.svg)](https://github.com/goatshriek/stumpless-logger/actions/workflows/linux.yml) [![Windows Builds](https://github.com/goatshriek/stumpless-logger/actions/workflows/windows.yml/badge.svg)](https://github.com/goatshriek/stumpless-logger/actions/workflows/windows.yml) [![Mac Builds](https://github.com/goatshriek/stumpless-logger/actions/workflows/mac.yml/badge.svg)](https://github.com/goatshriek/stumpless-logger/actions/workflows/mac.yml) +[![Gitter](https://badges.gitter.im/stumpless/community.svg)](https://gitter.im/stumpless/community?utm_source=badge&utm_medium=badge&utm_campaign=pr-badge) [![Apache 2.0 License](https://img.shields.io/badge/license-Apache%202.0-blue.svg)](https://opensource.org/licenses/Apache-2.0) [![Contributor Covenant](https://img.shields.io/badge/Contributor%20Covenant-v2.1-ff69b4.svg)](https://github.com/goatshriek/stumpless-logger/blob/latest/docs/CODE_OF_CONDUCT.md) - -**An enhanced command line logging utility.** +[Key Features](#key-features) | +[Basic Usage](#send-your-logs-anywhere) | +[Contributing](#contributing) ## Key Features @@ -219,3 +224,44 @@ familiar with or using other loggers. different combinations in a single invocation. * The following flags/modes of operation are not supported: * `--rfc3164` for the RFC 3164 BSD syslog format of messages + + +## Contributing +Notice a problem or have a feature request? Just create an issue using one of +the templates, and we will respond as quickly as we can. You can also look at +the project's [Contribution Guidelines](docs/CONTRIBUTING.md) for more details +on the different ways you can give back to the open source community! + +If you want to actually write some code or make an update yourself, there are a +few options based on your level of experience and familiarity with making +contributions. + +The first option is to browse the list of issues that are marked with the label +[good first issue](https://github.com/goatshriek/stumpless-logger/issues?q=is%3Aissue+is%3Aopen+label%3A%22good+first+issue%22). +These issues are selected to be a small but meaningful amount of work, and +include details on the general approach that you can take to complete them. They +are a great place to start if you are just looking to test the waters of this +project or open source contribution in general. + +More experienced developers may prefer to look at the full list of issues on the +project, as well as the +[roadmap](https://github.com/goatshriek/stumpless-logger/blob/latest/docs/roadmap.md). +If an item catches your interest, drop a comment in the existing issue or open +a new one if it doesn't exist yet and state your intent to work on it so that +others will have a way to know it is underway. + +Or perhaps you are just looking for a way to say thanks! If that's the case or +if there is something that you would prefer to drop me a private message about, +please feel free to do so on Twitter with +[#StumplessLib](https://twitter.com/search?q=%23StumplessLib), or in an +[email](mailto:joelanderson333@gmail.com)! I'd love to see you share the project +with others or just hear your thoughts on it. + + +## Further Documentation +If you're curious about how something in stumpless works that isn't explained +here, you can check the appropriate section of the documentation, stored in the +docs folder of the repository. Folders in the repository contain their own +README files that detail what they contain and any other relevant information. +If you still can't find an answer, submit an issue or head over to +[gitter](https://gitter.im/stumpless/community) and ask for some help. diff --git a/docs/CONTRIBUTING.md b/docs/CONTRIBUTING.md new file mode 100644 index 0000000..b2b4e34 --- /dev/null +++ b/docs/CONTRIBUTING.md @@ -0,0 +1,157 @@ +## Help Stumpless Do Better, Suck Less +Stumpless aims to do a small thing well while staying as small as possible. If +you've got a problem with the project, you have a great idea for a new feature, +or you just want to find a way to contribute, then check out the guidelines +below on how to get started. Also, please make sure that you adhere to the +[Code of Conduct](CODE_OF_CONDUCT.md) however you participate. + + +### **I know what I'm doing** +If you're a regular user of the library and know it pretty well, you can give +back to the community just by helping out others who have a question. Head over +to the project's [gitter](https://gitter.im/stumpless/community) room and if +there is a question that you can help with, don't hesitate to jump in! + + +### **It broke** +If you've got a problem with the project, please make sure that you've done the +following things before submitting an issue: + + * Review the documentation to ensure that the behavior is unintentional + * Search through the other issues on the project to ensure that this is not + already captured + * Replicate the problem from the latest version branch + +If you've completed all of these steps and the problem persists, submit an issue +on the [GitHub project](https://github.com/goatshriek/stumpless-logger) using +the provided issue template with all information filled in. + +Even better: if you know how to fix the issue, go ahead and submit a pull +request using the provided template, mentioning the corresponding issue number. + + +### **I'm helping!** +Made some changes and want to share your work? Great! Submit a pull request and +we'll review it for inclusion into the latest version. Make sure that you follow +these guidelines: + * If you're working on something that's relatively small, then you don't need + to worry about the number of commits in your branch, as it will be squashed + before it is merged into the `latest` branch. If you're working on something + marked as a `good first issue` for example, don't worry about keeping a clean + commit history and just focus on the fun stuff! You will be retained as the + author of the commit, to make sure that contribution credit is reflected + in the commit history and on GitHub. + * If you're working on something larger, squashing it into a + single commit might not make a lot of sense, and so the number of commits + becomes more important. If you find yourself in this situation, try to make + sure that each commit is logical and adds value to the commit history. If + you need a little guidance to get started with adjusting the commit history + of your change, check out + [this chapter](https://git-scm.com/book/en/v2/Git-Tools-Rewriting-History) + from the Git Book about it, which covers several common adjustments. Note + that this scenario will be rare, and if you aren't sure if it applies to + your change then you should ask before going down the complex and + time-consuming path of rebasing. + * If a commit resolves or is otherwise related to a particular issue, include + a reference to it in the body of the commit. + + +### **It would be great if...** +If you have a new feature that you think would be worthwhile, please open an +issue on the github project using the 'Feature Request' template. If it fits +with the project then you can begin working on a fork and submit a pull +request of your branch so that we can watch it progress and merge it in once +it is complete. Or if you don't have time we will add it to the project +[roadmap](roadmap.md) and eventually implement it depending on other priorities. + + +### **Things we don't accept** +We appreciate anyone looking to contribute to the project! However, we also need +to make sure that we make the best use our time spent supporting the project and +its contributors. For this reason, some types of contributions will not be +accepted by the project team. We ask potential contributors to review this list +and make sure that they steer clear of these types of pull requests: + * Corrections of obvious spelling errors and grammatical problems may be + accepted on a case-by-case basis, based on the severity of the problem + addressed. Changes of this nature have a higher probability of being accepted + if there are more changes in them than a single one. Put simply, if you want + to do a proofreading contribution, you need to proofread more than a single + document, and not stop after finding a single problem. We strongly recommend + you spend your time contributing in some other way. + * Changes of capitalization, punctuation, or other style choices will not be + accepted. + + +### **I don't know where to start** +If you'd like to contribute but aren't quite sure where to start, take a look at +the issues and see if there is anything there that you think you can tackle! In +particular, the 'help wanted' and 'good first issue' labels mark issues that +need attention and are relatively simple to fix, respectively. Issues marked as +'good first issue' are not time critical, so don't worry about timelines to +completion, as long as you check in occasionally if it is taking longer than +you initially thought. + + +#### No, I mean I **really** don't know where to start +If you are brand new to the community at large and are looking for a little more +detail on how to contribute, then this section should help you get started. + +Stumpless has a default branch named `latest` off of which all new feature +branches are based. Once all changes planned for the next version have been +implemented, a tag will be added for the commit named after the semantic version +number and the `release` branch will be updated to point to this commit. In this +way, `latest` always has the most up to date changes and `release` always points +to the last complete version released. + +To create your own feature or update, you should fork the repository and create +a new branch based on the `latest` branch. Don't forget to update the ChangeLog +with your changes, and when you're ready open a pull request against `latest`. + +It is unusual, but you may find that it is more appropriate to base your branch +on the `release` branch instead of `latest`. Some examples of these types of +changes are: + * updates to project documentation that is relevant to the current version of + the project as well as the next + * patches that need to be applied to the current version of the library in + order to fix broken functionality (note that this will require updating the + library to the next patch level, for example from 1.3.2 to 1.3.3) + +Be sure to check out the [dependencies](dependencies.md) list to make sure that +your development environment has all of the necessary tools. More specifically, +make sure that you are able to run the tests and development tools before you +make extensive changes, so that you can test iteratively as you go. + +A detailed tutorial on the traditional git flow style of development is beyond +the scope of the project documentation, but the following guides serve as good +starting material: + * [GitHub Guides](https://guides.github.com/introduction/flow/) + * [Creating a Pull Request from a Fork](https://help.github.com/en/github/collaborating-with-issues-and-pull-requests/creating-a-pull-request-from-a-fork) + +To recap, your basic steps will be to fork the repository, create a new branch +based on `latest` (or perhaps `release` depending on the circumstances), and +when you are finished adding commits to it create a pull request back to the +main repository. + + +### You still there? +The project team aims to be as responsive as we can, typically responding to +new issues and pull requests within a few days. Asking for clarification on an +issue or requesting changes to a pull request is fairly common, and often some +back and forth is needed before something can be accepted. + +Unfortunately, sometimes these conversations stall and no progress is made. In +cases where this happens and the project team is waiting for a response, the +item will eventually be closed as stale. Items that have had no response for +two months will be labeled as stale, and a warning will be posted in the +discussion. If another month passes with no response, then the item will be +closed as stale. + +Stale items can always be reopened, so don't feel like the discussion is over +forever if something gets closed! We just want to keep our active work nice +and tidy for everyone to quickly see what we're doing (and what we aren't). + + +## Thanks! +And no matter how you contribute, thanks for giving back to the community! + +Stumpless Team diff --git a/docs/SECURITY.md b/docs/SECURITY.md new file mode 100644 index 0000000..b7ff6ff --- /dev/null +++ b/docs/SECURITY.md @@ -0,0 +1,33 @@ +# Stumpless Security Policy +This document describes the security support for Stumpless, including versions +that will be patched and the procedure for submitting vulnerabilities. It also +includes security-relevant guidance on how to use the library, and particular +pitfalls that must be avoided to ensure that vulnerabilities are not introduced +into the system. + + +## Supported Versions +The table below lists the current supported versions of Stumpless. Generally, +the current and previous major versions are supported at their highest minor +version. + +| Version | Supported | +| ------- | ------------------ | +| 0.2.x | :heavy_check_mark: | +| <= 0.1 | :x: | + + +## Reporting a Vulnerability +If you discover a problem with Stumpless, please report it immediately to the +project owner, [Joel Anderson](mailto:joelanderson333@gmail.com). The issue +will be investigated as soon as possible and you will receive a response within +14 days of the message. + +A fix will be deployed to all affected supported versions with a high priority. +However, there is currently no guaranteed timeline for the patch as the project +does not have any dedicated resources. + +You can increase the speed and effectiveness of the response by including as +much detail in your report as possible. Suggested fixes are welcome as well, +though we ask that you keep your fixes limited to private correspondence until +a fix can be deployed to limit the risk to users of the library in the meantime. diff --git a/docs/dependencies.md b/docs/dependencies.md new file mode 100644 index 0000000..31b6509 --- /dev/null +++ b/docs/dependencies.md @@ -0,0 +1,6 @@ +## Build Environment +Almost all of the build environment for the stumpless logger is provided by the +Rust and Cargo toolchains. However, as a result of the dependency on the +`stumpless-sys` crate, which builds the C library, you will also need: + * `cmake` for build targets and orchestration + * a toolchain that can be used by cmake (gcc, for example) diff --git a/docs/roadmap.md b/docs/roadmap.md new file mode 100644 index 0000000..1f44828 --- /dev/null +++ b/docs/roadmap.md @@ -0,0 +1,72 @@ +# The Future of Stumpless +See below for details about upcoming releases of Stumpless. If you have feedback +or want to make a suggestion, please submit an issue on the project's +[Github page](https://github.com/goatshriek/stumpless-logger). + + +## 0.2.0 + * [CHANGE] **Avoid Thread Spawn for single target**: + When logs are only going to be sent to one target, the overhead of spawning + a new thread for the logging adds needless delay. This should be detected and + the thread spawn avoided in this situation. + * [CHANGE] **More forgiving param name/value parsing**: + Currently structured data params provided via `--sd-param` must include + double-quotes, the same was as `logger` does. However, this can be painful to + do in some environments where this requires different escape sequences based + on the shell in use. This will be changed to allow the double quotes to be + left out in scenarios where this is unnecessary. + + +## What you'll find here and what you wont +Stumpless is under active development, and has a long list of new features and +improvements waiting to be implemented. Some of these are detailed in the issues +list on the project Github website, but this is certainly not a comprehensive +list of planned updates. Similarly, work that is in progress on new features is +tracked as a project on the Github repository, but future planned work does not +exist there either. Instead, the plans for future direction are kept here, in +the project roadmap. + +Items are added to the roadmap once they have been identified, assessed for +level of effort, and prioritized based on community needs. Each item is assigned +to a semantic version, along with its change type, a description, and the +reasoning behind it. Where they exist, you will see references to issues on the +Github repository where you can go for more details on the origin of the +request. Once a version is in work, you will be able to find a corresponding +project on the Github repository with each roadmap item listed as a task. Once +all tasks are complete, the version will be released and the next started. + +Once an item has been implemented it will be removed from the roadmap. If you +would like to see a history of changes on the existing codebase, check out the +ChangeLog (ChangeLog.md in the project root) to see what was included in each +version of the library. In most cases, roadmap items will be removed from this +document and placed there upon completion. + +Note that the timelines associated with each change are vague at best. The +project team is not currently big enough to realistically make any promises, so +timing is often left out to prevent folks from feeling cheated if something +takes longer than expected. + + +## A Note about Github issues and projects +A fair question to ask is why the roadmap is not being managed within the issue +and project features of Github itself, since this is where the project is +currently hosted. Indeed, suggestions submitted by the community are tracked as +issues, and projects are already created for ongoing work. There are a few +reasons that a separate roadmap is maintained: + * **Issues are used to exclusively track bugs and community requests.** + This certainly isn't a hard and fast rule, and isn't followed by many other + projects, but it is how Wrapture is managed. Keeping the issue count as a + clear indicator of known problems and community requests lets the project + maintainers (and anyone interested in looking at how well it is being + maintained) immediately see how much outstanding work exists. Of course, + the roadmap may have features requested by the community or enhancements made + clear by bug reports, but it will also have a number of features and tweaks + that have a lower priority. + * **Project direction should come packaged with the product.** + Again this isn't a commonly followed rule, but it is one that the project + author follows. Anyone that obtains the source code of the project at a + single point in time should be able to quickly see the current direction of + the project. Maintaining the roadmap within the version control of the source + itself facilitates this, the same way that licensing and copyright + notifications are traditionally bundled with code. And if you don't care, + you can always ignore them.