Skip to content

Commit 1136155

Browse files
committed
feat(docs): Preparing project for Contributor License Agreements and getting major project documentation ready.
1 parent 689aec7 commit 1136155

15 files changed

Lines changed: 260 additions & 3 deletions

File tree

.markdownlint.yaml

Lines changed: 38 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,38 @@
1+
---
2+
# Enable all built-in rules by default
3+
default: true
4+
5+
# MD007/ul-indent: Set unordered list indentation to 2 spaces
6+
MD007:
7+
indent: 2
8+
9+
# MD013/line-length: Disable or adjust long line warnings
10+
# Many developers disable this to allow long URLs or technical prose
11+
MD013: false
12+
13+
# MD022/blanks-around-headings: Headings should be surrounded by blank lines
14+
# Disabling this allows headings to be immediately preceded or followed by text
15+
MD022: false
16+
17+
# MD024/no-duplicate-heading: Allow duplicate headings if they are not siblings
18+
MD024:
19+
siblings_only: true
20+
21+
# MD029/ol-prefix: Use 1. 2. 3. for ordered lists (default is "one" i.e., 1. 1. 1.)
22+
MD029:
23+
style: "ordered"
24+
25+
# MD032/blanks-around-lists: Lists should be surrounded by blank lines
26+
# Setting this to false ignores the rule entirely
27+
MD032: false
28+
29+
# MD033/no-inline-html: Allow specific HTML tags if needed
30+
MD033:
31+
allowed_elements: ["br", "details", "summary"]
32+
33+
# MD041/first-line-h1: Ensure the file starts with a top-level heading
34+
MD041: true
35+
36+
# MD046/code-block-style: Enforce fenced code blocks (```)
37+
MD046:
38+
style: "fenced"

changelogs/CHANGELOG.md

Lines changed: 10 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -31,6 +31,16 @@
3131
- Merge pull request #19 from jcook3701/develop
3232

3333
Feat 004 (#18)
34+
- Merge pull request #20 from jcook3701/feat-005
35+
36+
Feat (005)
37+
- Merge pull request #21 from jcook3701/develop
38+
39+
Develop
40+
41+
### 🐛 Fixed
42+
43+
- *(template)* Updates to template cookiecutter.json file.
3444
## [0.1.0] - 2025-12-05
3545

3646
### ⚙️ Miscellaneous

changelogs/releases/v0.1.1.md

Lines changed: 11 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -2,7 +2,7 @@
22
# Changelog:
33
# --------------------------------------------------
44

5-
## [0.1.1] - 2026-01-06
5+
## [0.1.1] - 2026-01-14
66

77
### ⚙️ Miscellaneous
88

@@ -31,3 +31,13 @@
3131
- Merge pull request #19 from jcook3701/develop
3232

3333
Feat 004 (#18)
34+
- Merge pull request #20 from jcook3701/feat-005
35+
36+
Feat (005)
37+
- Merge pull request #21 from jcook3701/develop
38+
39+
Develop
40+
41+
### 🐛 Fixed
42+
43+
- *(template)* Updates to template cookiecutter.json file.

cookiecutter.json

Lines changed: 8 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -14,6 +14,14 @@
1414
"linkedin_usercode": "jared-cook-b3585a114",
1515
"twitter_username": "",
1616
"buymeacoffee_username": "jcook3701",
17+
"template_type": [
18+
"ansible",
19+
"c/c++",
20+
"cookiecutter",
21+
"python",
22+
"ros2",
23+
"typescript"
24+
],
1725
"_is_sub_template": true,
1826
"_copy_without_render": [
1927
"README.md",
Lines changed: 116 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,116 @@
1+
# Contributing to {{ cookiecutter.project_name }}
2+
3+
You want to contribute to {{ cookiecutter.project_name }}? Welcome! Please read this document to understand what you can do:
4+
5+
* [Help Others](#help-others)
6+
* [Analyze Issues](#analyze-issues)
7+
* [Report an Issue](#report-an-issue)
8+
* [Contribute Code](#contribute-code)
9+
10+
## Help Others
11+
12+
You can help {{ cookiecutter.project_name }} by helping others who use it and need support.
13+
14+
## Analyze Issues
15+
16+
Analyzing issue reports can be a lot of effort. Any help is welcome!
17+
Go to [the GitHub issue tracker](https://github.com/{{ cookiecutter.github_username }}/{{ cookiecutter.project_slug }}/issues?state=open) and find an open issue which needs additional work or a bugfix (e.g. issues labeled with "help wanted" or "bug").
18+
19+
Additional work could include any further information, or a gist, or it might be a hint that helps understanding the issue. Maybe you can even find and [contribute](#contribute-code) a bugfix?
20+
21+
## Report an Issue
22+
23+
If you find a bug - behavior of {{ cookiecutter.project_name }} code contradicting your expectation - you are welcome to report it.
24+
We can only handle well-reported, actual bugs, so please follow the guidelines below.
25+
26+
Once you have familiarized with the guidelines, you can go to the [GitHub issue tracker for {{ cookiecutter.project_name }}](https://github.com/{{ cookiecutter.github_username }}/{{ cookiecutter.project_slug }}/issues/new) to report the issue.
27+
28+
### Quick Checklist for Bug Reports
29+
30+
Issue report checklist:
31+
* Real, current bug
32+
* No duplicate
33+
* Reproducible
34+
* Good summary
35+
* Well-documented
36+
* Minimal example
37+
<!-- * Use the [template](ISSUE_TEMPLATE.md) -->
38+
39+
### Issue handling process
40+
41+
When an issue is reported, a committer will look at it and either confirm it as a real issue, close it if it is not an issue, or ask for more details.
42+
43+
An issue that is about a real bug is closed as soon as the fix is committed.
44+
45+
### Reporting Security Issues
46+
47+
If you find a security issue, please act responsibly and report it not in the public issue tracker, but directly to us, so we can fix it before it can be exploited.
48+
Please send the related information to <jcook3701+{{ cookiecutter.project_slug }}@gmail.com>.
49+
50+
### Usage of Labels
51+
52+
GitHub offers labels to categorize issues. We defined the following labels so far:
53+
54+
Labels for issue categories:
55+
* bug: this issue is a bug in the code
56+
* feature: this issue is a request for a new functionality or an enhancement request
57+
* design: this issue relates to the UI or UX design of the tool
58+
59+
Status of open issues:
60+
* help wanted: the feature request is approved and you are invited to contribute
61+
62+
Status/resolution of closed issues:
63+
* wontfix: while acknowledged to be an issue, a fix cannot or will not be provided
64+
65+
The labels can only be set and modified by committers.
66+
67+
### Issue Reporting Disclaimer
68+
69+
We want to improve the quality of {{ cookiecutter.project_name }} and good bug reports are welcome! But our capacity is limited, thus we reserve the right to close or to not process insufficient bug reports in favor of those which are very cleanly documented and easy to reproduce. Even though we would like to solve each well-documented issue, there is always the chance that it will not happen - remember: {{ cookiecutter.project_name }} is Open Source and comes without warranty.
70+
71+
Bug report analysis support is very welcome! (e.g. pre-analysis or proposing solutions)
72+
73+
## Contribute Code
74+
75+
You are welcome to contribute code to {{ cookiecutter.project_name }} in order to fix bugs or to implement new features.
76+
77+
There are three important things to know:
78+
1. You must be aware that you need to submit [Developer Certificate of Origin](https://developercertificate.org/) in order for your contribution to be accepted. This is common practice in all major Open Source projects.
79+
2. There are **several requirements regarding code style, quality, and product standards** which need to be met (we also have to follow them). The respective section below gives more details on the coding guidelines.
80+
3. **Not all proposed contributions can be accepted**. Some features may e.g. just fit a third-party add-on better. The code must fit the overall direction of {{ cookiecutter.project_name }} and really improve it. The more effort you invest, the better you should clarify in advance whether the contribution fits: the best way would be to just open an issue to discuss the feature you plan to implement (make it clear you intend to contribute).
81+
82+
## Developer Certificate of Origin (DCO)
83+
84+
Due to legal reasons, contributors will be asked to accept a DCO before they submit the first pull request to this projects, this happens in an automated fashion during the submission process. We use [the standard DCO text of the Linux Foundation](https://developercertificate.org/).
85+
86+
### Contribution Content Guidelines
87+
88+
These are some of the rules we try to follow:
89+
* Apply a clean coding style adapted to the surrounding code, even though we are aware the existing code is not fully clean
90+
* Use (4)spaces for indentation (except if the modified file consistently uses tabs)
91+
* Use variable naming conventions like in the other files you are seeing (underscore)
92+
* No console.log() - use logging service
93+
* Run all ci/cd code checks and make sure they succeed
94+
* Comment your code where it gets non-trivial
95+
* Keep an eye on performance and memory consumption, properly destroy objects when not used anymore
96+
* Write a unit test
97+
* Do not do any incompatible changes, especially do not modify the name or behavior of public API methods or properties
98+
99+
### How to contribute - the Process
100+
101+
1. Make sure the change would be welcome (e.g. a bugfix or a useful feature); best do so by proposing it in a GitHub issue
102+
2. Create a branch forking the {{ cookiecutter.project_slug }} repository and do your change
103+
3. Commit and push your changes on that branch
104+
4. In the commit message
105+
* Describe the problem you fix with this change.
106+
* Describe the effect that this change has from a user's point of view. App crashes and lockups are pretty convincing for example, but not all bugs are that obvious and should be mentioned in the text.
107+
* Describe the technical details of what you changed. It is important to describe the change in a most understandable way so the reviewer is able to verify that the code is behaving as you intend it to.
108+
5. If your change fixes an issue reported at GitHub, add the following line to the commit message:
109+
* ```Fixes #(issueNumber)```
110+
* Do NOT add a colon after "Fixes" - this prevents automatic closing.
111+
6. Create a Pull Request
112+
7. Follow the link posted by the {{ cookiecutter.project_name }} to your pull request and accept it, as described in detail above.
113+
8. Wait for our code review and approval, possibly enhancing your change on request
114+
* Note that the {{ cookiecutter.project_name }} developers also have their regular duties, so depending on the required effort for reviewing, testing and clarification this may take a while
115+
9. Once the change has been approved we will inform you in a comment
116+
10. We will close the pull request, feel free to delete the now obsolete branch
Lines changed: 13 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,13 @@
1+
# Security Vulnerabilities
2+
3+
The {{ cookiecutter.project_name }} is built with security and data privacy in mind to ensure your data is safe.
4+
5+
## Reporting
6+
We are grateful for security researchers and users reporting a vulnerability to us, first. To ensure that your request is handled in a timely manner and non-disclosure of vulnerabilities can be assured, please follow the below guideline.
7+
8+
__Please do not report security vulnerabilities directly on GitHub. GitHub Issues can be publicly seen and therefore would result in a direct disclosure.__
9+
10+
For reporting a vulnerability, please send an email directly to <jcook3701+{{ cookiecutter.project_slug }}-security@gmail.com>. Please address questions about data privacy, security concepts, and other media requests for Security Researchers on our team.
11+
12+
## Disclosure Handling
13+
We are committed to timely review and respond to your request. The resolution of code defects will be handled by a dedicated group of security experts and prepared in a private GitHub repository. The project will inform the public about resolved security vulnerabilities via GitHub Security Advisories.

{{ cookiecutter.project_slug }}/_config.yml

Lines changed: 10 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -9,10 +9,12 @@ remote_theme: "{{ cookiecutter.theme }}"
99
ga_tracking: "{{ cookiecutter.ga_tracking }}"
1010

1111
repo_name: "{{ cookiecutter.project_slug }}"
12-
baseurl: "/{{ cookiecutter.project_slug }}"
1312
repo_url: >
1413
https://github.com/{{ cookiecutter.github_username }}/{{ cookiecutter.project_slug }}
1514
15+
# Specifies the site's subpath for correct URL generation
16+
baseurl: "/{{ cookiecutter.project_slug }}"
17+
1618
# Author Remote User Accounts
1719
# twitter_username: "{{ cookiecutter.twitter_username }}"
1820
github_username: "{{ cookiecutter.github_username }}"
@@ -118,6 +120,13 @@ callouts:
118120
title: Warning
119121
color: red
120122

123+
collections:
124+
manual:
125+
output: true
126+
permalink: /:manual/:path/
127+
128+
collections_dir: .
129+
121130
plugins:
122131
- jekyll-seo-tag
123132
- jekyll-github-metadata
Lines changed: 7 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,7 @@
1+
---
2+
layout: default
3+
title: CLA
4+
nav_order: 1
5+
parent: Developer Resources
6+
---
7+
# {{ cookiecutter.project_name }} Software Grant and Contributor License Agreement ("Agreement")
Lines changed: 7 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,7 @@
1+
---
2+
layout: default
3+
title: Contribute
4+
nav_order: 1
5+
parent: Developer Resources
6+
---
7+
# Contribute to {{ cookiecutter.project_name }}
Lines changed: 14 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,14 @@
1+
2+
---
3+
layout: default
4+
title: "Developer Resources"
5+
nav_order: 1
6+
parent: {{ cookiecutter.project_name }}
7+
---
8+
# Developer resources
9+
10+
This section of the documentation contains additional resources for developers and contributors.
11+
12+
# Contribute to {{ cookiecutter.project_name }}
13+
14+
Refer to the [Contribute to {{ cookiecutter.project_name }}]() guide to learn the various ways you can contribute to {{ cookiecutter.project_name }}. Read the [{{ cookiecutter.project_name }} Software Grant and Contributor License Agreement]() before making any contribution.

0 commit comments

Comments
 (0)