Skip to content

Commit 3277f80

Browse files
caarloshenriqcaarloshenriq
committed
docs(contributing): clarify repository purpose and contribution
standards
1 parent fd2a611 commit 3277f80

2 files changed

Lines changed: 279 additions & 3 deletions

File tree

‎CONTRIBUTING.md‎

Lines changed: 275 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,275 @@
1+
# Contributing Guidelines
2+
3+
Thanks for helping improve the BitDevs Socratic Seminar archive!
4+
5+
This document defines the scope, rules, and workflow for contributing to the repository.
6+
Instructions for creating or updating meetup posts live in the README.
7+
8+
This document explains **what** we accept and **how** to contribute so we stay consistent.
9+
10+
## Contents
11+
- [Scope of contributions](#scope-of-contributions)
12+
- [Citation & link policy](#citation--link-policy)
13+
- [Style guide (Markdown)](#style-guide-markdown)
14+
- [Contribution workflow](#contribution-workflow)
15+
- [Branch naming conventions](#branch-naming-conventions)
16+
- [Commit message conventions](#commit-message-conventions)
17+
- [Pull Request (PR) process](#pull-request-pr-process)
18+
- [Squashing & merge strategy](#squashing--merge-strategy)
19+
20+
---
21+
22+
## Scope of contributions
23+
24+
This repository accepts two main types of contributions:
25+
26+
- **Meetup-related content**: topics, links, summaries, and corrections for specific Socratic seminars.
27+
- **General repository maintenance**: documentation, layouts, scripts, CI configuration, and other housekeeping.
28+
29+
This guide focuses on defining what is in scope and how contributions should be made.
30+
Workflow and naming rules apply to all contribution types.
31+
32+
33+
### Accepted contributions
34+
35+
#### General repository maintenance
36+
- Documentation improvements
37+
- Layout and styling changes
38+
- Scripts, tooling, and CI configuration
39+
- Refactors that improve consistency or maintainability
40+
41+
#### Meetup-related contributions
42+
- Topic summaries and background material
43+
- Curated resource lists (papers, PRs, BIPs, mailing-list threads)
44+
- Corrections and structural improvements
45+
- New templates that improve the contributor experience
46+
47+
48+
### Out of scope
49+
50+
- Opinionated or editorial content unless explicitly approved
51+
- Content unrelated to Bitcoin or Socratic Seminar discussions
52+
- Promotional or low-signal material
53+
54+
---
55+
56+
If you only want to **propose topics** (without editing files yourself), you can open an Issue like:
57+
58+
> `Topics for Socratic #NNN`
59+
60+
and list the suggested links. In that case, the sections **Citation & link policy**, and **Style guide (Markdown)** are the most relevant.
61+
62+
---
63+
64+
## Citation & link policy
65+
66+
This archive is meant to point to **public resources** and capture **what was discussed**, not who said what in the room.
67+
68+
When adding topics:
69+
70+
- Prefer **canonical, stable URLs**:
71+
- Bitcoin Core / other repos on GitHub
72+
- BIPs from the official BIPs repository
73+
- bitcoin-dev / delvingbitcoin threads
74+
- arXiv papers, project documentation, blog posts
75+
- Avoid:
76+
- URL shorteners whenever possible
77+
- Tracking parameters (`utm_*`, etc.) when it doesn't break the link
78+
- X/Twitter links are acceptable if they are the main source
79+
- Respect privacy:
80+
- Don't link to **private chat logs**, closed groups, or personal DMs
81+
- Don't include personal data about attendees (emails, phone numbers, doxxing, etc.)
82+
- When summarizing ideas from participants, it's fine to keep it anonymous unless they already publish under that identity
83+
84+
---
85+
86+
## Style guide (Markdown)
87+
88+
To keep the archive consistent and easy to read:
89+
90+
- **Headings**
91+
- Start sections at `##` and use `###` for subsections.
92+
- Use a small, predictable set of sections, for example:
93+
- `## Avisos` / `## Announcements`
94+
- `### Bitcoin`, `### Lightning`, `### Mining`, `### Maneiro` / `### Misc`.
95+
96+
- **Lists**
97+
- Use bullet lists for topics, with descriptive link text:
98+
99+
* [BIP-444: Reduced Data Temporary Softfork](https://github.com/bitcoin/bips/pull/2017) - softfork proposal to reduce block data.
100+
* [LND 0.20.0-rc2](https://github.com/lightningnetwork/lnd/releases/tag/v0.20.0-beta.rc2)
101+
102+
- Prefer **descriptive link text** instead of bare URLs.
103+
104+
- **Language**
105+
- File content can follow the meetup's usual language (e.g. Portuguese or English).
106+
- **Commit messages and PR descriptions should always be in English.**
107+
108+
- **Formatting details**
109+
- Try to wrap lines around ~100 characters to keep diffs readable.
110+
- Avoid trailing whitespace and unnecessary blank lines.
111+
- Keep YAML front-matter and indentation consistent with existing files.
112+
- When adding new files, copy from a recent existing post/template to match structure.
113+
114+
- **Code & configuration**
115+
- If you touch any scripts or configuration files:
116+
- Follow the existing style in that language (indentation, quoting, etc.).
117+
- Prefer small, focused changes that are easy to review.
118+
119+
---
120+
121+
## Contribution workflow
122+
123+
1. **Open an Issue** (optional but recommended for bigger changes) and describe what you'll add or fix.
124+
2. **Fork** the repo and create a feature branch:
125+
126+
git checkout -b docs/2025-10-seminar-notes
127+
128+
3. **Make your changes** and commit them with a meaningful message.
129+
4. **Push your changes** to your forked repository:
130+
131+
git push origin docs/2025-10-seminar-notes
132+
133+
5. **Open a Pull Request (PR)** to the main repository and link it to the Issue (if applicable).
134+
135+
Try to keep each PR focused on **one meetup** or **one logical change** (e.g. "fix broken links in September 2025 post").
136+
137+
---
138+
139+
## Branch naming conventions
140+
141+
Use short, lowercase names with words separated by hyphens and, when useful, a simple prefix.
142+
143+
Recommended patterns:
144+
145+
- `feat/...` - new content or features
146+
- `fix/...` - bug fixes or corrections
147+
- `docs/...` - documentation-only changes (README, CONTRIBUTING, templates)
148+
- `chore/...` - maintenance, refactors, or build-related changes
149+
150+
Examples:
151+
152+
- `feat/2025-11-socratic-040`
153+
- `docs/add-contributing-guide`
154+
- `fix/typo-2025-09-topics`
155+
- `chore/reorder-readme`
156+
157+
If you create the branch from the GitHub UI, try to avoid generic names like `patch-1` and prefer something descriptive.
158+
159+
---
160+
161+
## Commit message conventions
162+
163+
We follow a style based on [Conventional Commits](https://www.conventionalcommits.org/en/v1.0.0/), for example:
164+
165+
- `feat: nov meetup`
166+
- `feat(header): add X (@curitibabitdevs) link to navigation`
167+
- `feat(_posts): arkade announcement`
168+
- `fix(_posts): update meetup links`
169+
- `fix: remove duplicated topics`
170+
- `2025-09 (#68)`
171+
172+
General rules:
173+
174+
- Write commit messages in **English**.
175+
- Start with a **type**, optional **scope**, then a **short description**:
176+
177+
<type>(optional-scope): short description
178+
179+
- Keep the subject line concise (ideally ≤ 50 characters).
180+
- Use the body (optional) to explain **why** you're changing something, not just **what** changed.
181+
182+
Common types:
183+
184+
- `feat` - new posts, new sections, or new functionality
185+
- `fix` - corrections that change what readers/users see (broken links, wrong dates, incorrect metadata, typos that change meaning)
186+
- `docs` - README, CONTRIBUTING, or other documentation-only updates
187+
- `chore` - repository maintenance (moving/renaming files, updating CI or dependencies, non-user-visible cleanups)
188+
- `refactor` - improving structure of build/automation scripts without changing their output
189+
- `style` - purely stylistic changes (whitespace, line wrapping, indentation) with no change in meaning
190+
- `test` - adding or adjusting tests (if the repo grows tests later)
191+
192+
In practice:
193+
194+
- Use `fix` when something is "wrong" from the reader's point of view (404 links, incorrect info, broken formatting in the rendered page).
195+
- Use `style` when you're only changing formatting/whitespace for readability.
196+
- Use `refactor` when you're improving the structure of helper scripts or config without changing behavior.
197+
- Use `chore` for general housekeeping that doesn't fit the above (moving posts, updating CI configs, bumping dependencies).
198+
199+
Examples for this repository:
200+
201+
- `feat(topics): add socratic seminar 040`
202+
- `feat(posts): add nov 2025 meetup`
203+
- `fix(links): update delvingbitcoin URLs for september`
204+
- `docs: add contribution guidelines`
205+
- `chore(posts): reorder sections by topic`
206+
207+
If you are working on a seminar topic file and that's the only change in the PR, a short and focused subject like below is fine:
208+
209+
- `2025-09: add socratic seminar topics`
210+
211+
---
212+
213+
## Pull Request (PR) process
214+
215+
When opening a PR, please:
216+
217+
1. **Keep it focused.**
218+
Ideally, one PR = one meetup post or one small set of related fixes.
219+
220+
2. **Sync with `main`** before opening:
221+
222+
git fetch upstream
223+
git checkout main
224+
git pull upstream main
225+
git checkout your-branch
226+
git rebase main
227+
228+
3. **Run checks locally** if the repository provides them (e.g. linters, test scripts, or static site build).
229+
Example: `make` / `make test` / `jekyll serve`, as documented in the README.
230+
231+
4. **Write a clear PR description.**
232+
A simple template you can follow:
233+
234+
Summary
235+
-------
236+
- Add topics for the November 2025 Socratic seminar.
237+
- Include links to BIPs, PRs, and Delving Bitcoin threads.
238+
239+
Details
240+
-------
241+
- Meetup date: 2025-11-05
242+
- Sections: Announcements, Bitcoin, Lightning, Misc
243+
244+
Checklist
245+
---------
246+
- [ ] Links render correctly in Markdown preview
247+
- [ ] No private or non-public resources referenced
248+
249+
5. **Address review comments.**
250+
- Push follow-up commits to the same branch.
251+
- **Clean history approach**: Feel free to amend commits and force-push with `--force-with-lease` to keep history clean—just leave a comment in the PR describing your changes.
252+
- Alternatively, you can add new commits for each review round; maintainers will squash at merge time if needed.
253+
254+
---
255+
## Squashing & merge strategy
256+
257+
To keep the history readable, we generally:
258+
259+
- Use **"Squash and merge"** for most PRs so that each PR becomes a **single logical commit** on `main` (often one commit per meetup or per change-set).
260+
- Occasionally keep multiple commits (regular merge) when the history inside the PR is meaningful on its own.
261+
262+
Force-pushing (`git push --force-with-lease`) to your **own feature branches** is a common practice to keep the commit history clean, especially **before** a PR is opened or when you're squashing WIP commits.
263+
264+
Once a PR already has review comments, prefer adding new commits instead of rewriting history, unless a maintainer explicitly asks you to rebase or clean up the branch.
265+
266+
What this means for contributors:
267+
268+
- You **don't need** perfectly clean commits while you are iterating on your branch.
269+
- It's nice (but not mandatory) to clean up obvious "WIP" commits before asking for review.
270+
- Maintainers will pick an appropriate merge strategy. If we squash, we'll make sure the final commit message follows the conventions above.
271+
272+
Please:
273+
274+
- Never push directly to `main`.
275+
- Avoid force-pushing to branches that already have review comments unless you're explicitly asked to rebase/cleanup.

‎README.md‎

Lines changed: 4 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -14,7 +14,7 @@ site locally. Once they're setup:
1414

1515
## Making a Post
1616

17-
To make a new post, make a new file in `_posts/` with a title of
17+
To make a new post, create a new file in `_posts/` based on the [template](_posts/_template.md) with a title of
1818
`YYYY-MM-DD-title-goes-here`. At the top of the file you'll want to provide the
1919
following information:
2020

@@ -23,10 +23,11 @@ following information:
2323
layout: post # Always post
2424
type: socratic # or whitepaper for a whitepaper series
2525
title: "Name of the Post"
26-
meetup: https://www.meetup.com/BitDevsNYC/events/[event id here]/
26+
meetup: https://www.meetup.com/curitiba-bitdevs/events/[event id here]/
2727
---
2828
```
2929

30+
Commit message example: feat(posts): add nov 2025
3031
After that, it's just simple markdown. The site will auto-generate the rest.
3132

3233
## Changing Site Data
@@ -38,4 +39,4 @@ Jekyll injects variables, so be sure to update both.
3839
## Attributions
3940

4041
Thanks to [LeNPaul](https://github.com/LeNPaul/jekyll-starter-kit) for the
41-
Jekyll starter kit this was forked from.
42+
Jekyll starter kit this was forked from.

0 commit comments

Comments
 (0)