docs(contributing): clarify repository purpose and contribution standards #34

caarloshenriq · 2025-11-20T00:13:53Z

This PR implements the contributing guidelines described in issue #8.

It adds a CONTRIBUTING.md that:

Describes the purpose of the repository as an archive of topics from our Socratic Bitcoin seminars.
Documents the contribution workflow (issues, branches, focused PRs).
Defines branch naming and commit message conventions.
Describes the PR review process and “Squash and merge” strategy.
Adds basic standards for Markdown style, links, and citations.

FelipeNegrelle

Hey, I've found some fixes that would improve reading experiences and some typos. Here's what I suggest to change:

Line 30: that improve contributor experience → that improve the contributor experience
Line 41: what you'fll add or fix → what you'll add or fix
Line 83: feat: november meetup → feat: November meetup
Line 113: feat(posts): add november 2025 meetup → feat(posts): add November 2025 meetup
Line 118: a short and focused subject like below is fine → a short and focused subject like the one below is fine

caarloshenriq · 2025-11-24T12:47:22Z

Hey, I've found some fixes that would improve reading experiences and some typos. Here's what I suggest to change:

Line 30: that improve contributor experience → that improve the contributor experience

Line 41: what you'fll add or fix → what you'll add or fix

Line 83: feat: november meetup → feat: November meetup

Line 113: feat(posts): add november 2025 meetup → feat(posts): add November 2025 meetup

Line 118: a short and focused subject like below is fine → a short and focused subject like the one below is fine

Thanks, your suggestions make sense.
I checked the commit history and it seems the project is using month abbreviations in commit messages (e.g. chore(posts): oct 2025), so I’m going to change to chore(post) nov 2025 for consistency.

FelipeNegrelle · 2025-11-24T13:09:51Z

Thanks, your suggestions make sense. I checked the commit history and it seems the project is using month abbreviations in commit messages (e.g. chore(posts): oct 2025), so I’m going to change to chore(post) nov 2025 for consistency.

LGTM

FelipeNegrelle

ACK

GustavoStingelin · 2025-11-25T16:49:05Z

@caarloshenriq pls, merge the two commits into a single one and force push

caarloshenriq · 2025-11-25T23:05:52Z

@caarloshenriq pls, merge the two commits into a single one and force push

merged

CONTRIBUTING.md

Copilot

Pull request overview

This PR establishes comprehensive contributing guidelines for a BitDevs Socratic Seminar archive repository. It creates a CONTRIBUTING.md file that codifies the project's contribution standards, workflow processes, and content conventions to ensure consistency across meetup documentation.

Key Changes:

Defines the repository's scope as an archive of Bitcoin Socratic seminar topics and resources
Documents a complete contribution workflow from issue creation through PR merge
Establishes conventions for branch naming, commit messages, and merge strategy

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.

CONTRIBUTING.md

standards

GustavoStingelin

Looking better, just left a few more comments.

GustavoStingelin · 2026-01-03T14:46:45Z

CONTRIBUTING.md

+Common types:
+
+- `feat` - new posts, new sections, or new functionality
+- `fix` - corrections that change what readers/users see (broken links, wrong dates, incorrect metadata, typos that change meaning)
+- `docs` - README, CONTRIBUTING, or other documentation-only updates
+- `chore` - repository maintenance (moving/renaming files, updating CI or dependencies, non-user-visible cleanups)
+- `refactor` - improving structure of build/automation scripts without changing their output
+- `style` - purely stylistic changes (whitespace, line wrapping, indentation) with no change in meaning
+- `test` - adding or adjusting tests (if the repo grows tests later)
+
+In practice:
+
+- Use `fix` when something is "wrong" from the reader's point of view (404 links, incorrect info, broken formatting in the rendered page).
+- Use `style` when you're only changing formatting/whitespace for readability.
+- Use `refactor` when you're improving the structure of helper scripts or config without changing behavior.
+- Use `chore` for general housekeeping that doesn't fit the above (moving posts, updating CI configs, bumping dependencies).
+
+Examples for this repository:
+
+- `feat(topics): add socratic seminar 040`
+- `feat(posts): add nov 2025 meetup`
+- `fix(links): update delvingbitcoin URLs for september`
+- `docs: add contribution guidelines`
+- `chore(posts): reorder sections by topic`
+
+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:
+
+- `2025-09: add socratic seminar topics`
+


I think this all can be removed, the first 15 lines of ## Commit message conventions are clear enough.

Suggested change

Common types:

- `feat` - new posts, new sections, or new functionality

- `fix` - corrections that change what readers/users see (broken links, wrong dates, incorrect metadata, typos that change meaning)

- `docs` - README, CONTRIBUTING, or other documentation-only updates

- `chore` - repository maintenance (moving/renaming files, updating CI or dependencies, non-user-visible cleanups)

- `refactor` - improving structure of build/automation scripts without changing their output

- `style` - purely stylistic changes (whitespace, line wrapping, indentation) with no change in meaning

- `test` - adding or adjusting tests (if the repo grows tests later)

In practice:

- Use `fix` when something is "wrong" from the reader's point of view (404 links, incorrect info, broken formatting in the rendered page).

- Use `style` when you're only changing formatting/whitespace for readability.

- Use `refactor` when you're improving the structure of helper scripts or config without changing behavior.

- Use `chore` for general housekeeping that doesn't fit the above (moving posts, updating CI configs, bumping dependencies).

Examples for this repository:

- `feat(topics): add socratic seminar 040`

- `feat(posts): add nov 2025 meetup`

- `fix(links): update delvingbitcoin URLs for september`

- `docs: add contribution guidelines`

- `chore(posts): reorder sections by topic`

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:

- `2025-09: add socratic seminar topics`

GustavoStingelin · 2026-01-03T14:48:39Z

CONTRIBUTING.md

+  - Start sections at `##` and use `###` for subsections.
+  - Use a small, predictable set of sections, for example:
+    - `## Avisos` / `## Announcements`
+    - `### Bitcoin`, `### Lightning`, `### Mining`, `### Maneiro` / `### Misc`.


Suggested change

- `### Bitcoin`, `### Lightning`, `### Mining`, `### Maneiro` / `### Misc`.

- `### Bitcoin`, `### Lightning`, `### Mining`, `### Misc`.

Let's not do this joke on the doc.

GustavoStingelin · 2026-01-03T14:52:30Z

CONTRIBUTING.md

+We follow a style based on [Conventional Commits](https://www.conventionalcommits.org/en/v1.0.0/), for example:
+
+- `feat: nov meetup`
+- `feat(header): add X (@curitibabitdevs) link to navigation`
+- `feat(_posts): arkade announcement`
+- `fix(_posts): update meetup links`
+- `fix: remove duplicated topics`
+- `2025-09 (#68)`


Let's keep it consistent.

Suggested change

We follow a style based on [Conventional Commits](https://www.conventionalcommits.org/en/v1.0.0/), for example:

- `feat: nov meetup`

- `feat(header): add X (@curitibabitdevs) link to navigation`

- `feat(_posts): arkade announcement`

- `fix(_posts): update meetup links`

- `fix: remove duplicated topics`

- `2025-09 (#68)`

We follow a style based on [Conventional Commits](https://www.conventionalcommits.org/en/v1.0.0/), for example:

- `feat(_posts): ago 2025`

- `feat(_posts): add arkade announcement`

- `fix(_posts): update meetup links`

- `feat(header): add X (@curitibabitdevs) link to navigation`

GustavoStingelin · 2026-01-03T14:57:16Z

CONTRIBUTING.md

+2. **Sync with `main`** before opening:
+
+       git fetch upstream
+       git checkout main
+       git pull upstream main
+       git checkout your-branch
+       git rebase main


We have both Contribution workflow and Pull Request process sections. They seem to cover the same ground, so we could unify them. This part can also be much shorter. We do not need to explain git basics to contributors opening a PR. A simple note like “make sure your branch is up to date with the master branch” should be enough.

GustavoStingelin · 2026-01-03T15:01:01Z

CONTRIBUTING.md

+## Squashing & merge strategy
+
+To keep the history readable, we generally:
+
+- 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).
+- Occasionally keep multiple commits (regular merge) when the history inside the PR is meaningful on its own.
+
+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.


We currently use squash because commit histories are often fragmented or poorly structured. Squashing allows the final commit to mainly reflect the PR title, which the maintainer can adjust before merging. That said, we prefer a clean and well structured commit history, since it allows us to use rebase and merge instead, preserving a clearer and more meaningful history.

Copilot

Pull request overview

Copilot reviewed 2 out of 2 changed files in this pull request and generated no new comments.

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.

FelipeNegrelle suggested changes Nov 23, 2025

View reviewed changes

caarloshenriq requested a review from FelipeNegrelle November 24, 2025 22:34

FelipeNegrelle approved these changes Nov 24, 2025

View reviewed changes

GustavoStingelin assigned GustavoStingelin and caarloshenriq and unassigned GustavoStingelin Nov 25, 2025

caarloshenriq force-pushed the docs/contributing-guidelines branch from e8f1740 to 1b67ade Compare November 25, 2025 23:04

GustavoStingelin requested changes Nov 28, 2025

View reviewed changes

CONTRIBUTING.md Outdated Show resolved Hide resolved

CONTRIBUTING.md Outdated Show resolved Hide resolved

CONTRIBUTING.md Show resolved Hide resolved

CONTRIBUTING.md Outdated Show resolved Hide resolved

GustavoStingelin requested a review from Copilot November 28, 2025 15:54

Copilot started reviewing on behalf of GustavoStingelin November 28, 2025 15:54 View session

Copilot finished reviewing on behalf of GustavoStingelin November 28, 2025 15:55

Copilot AI reviewed Nov 28, 2025

View reviewed changes

CONTRIBUTING.md Outdated Show resolved Hide resolved

caarloshenriq force-pushed the docs/contributing-guidelines branch from 1b67ade to a849426 Compare December 5, 2025 00:17

caarloshenriq requested a review from GustavoStingelin December 5, 2025 00:18

caarloshenriq removed their assignment Dec 5, 2025

GustavoStingelin assigned caarloshenriq Dec 5, 2025

GustavoStingelin requested a review from luisfg30 December 5, 2025 18:18

docs(contributing): clarify repository purpose and contribution

3277f80

standards

caarloshenriq force-pushed the docs/contributing-guidelines branch from a849426 to 3277f80 Compare January 2, 2026 18:28

GustavoStingelin requested changes Jan 3, 2026

View reviewed changes

GustavoStingelin requested a review from Copilot January 3, 2026 15:03

Copilot started reviewing on behalf of GustavoStingelin January 3, 2026 15:03 View session

Copilot AI reviewed Jan 3, 2026

View reviewed changes

	- `### Bitcoin`, `### Lightning`, `### Mining`, `### Maneiro` / `### Misc`.
	- `### Bitcoin`, `### Lightning`, `### Mining`, `### Misc`.

docs(contributing): clarify repository purpose and contribution standards #34

Are you sure you want to change the base?

docs(contributing): clarify repository purpose and contribution standards #34

Uh oh!

Conversation

caarloshenriq commented Nov 20, 2025

Uh oh!

FelipeNegrelle left a comment • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

caarloshenriq commented Nov 24, 2025

Uh oh!

FelipeNegrelle commented Nov 24, 2025

Uh oh!

FelipeNegrelle left a comment

Choose a reason for hiding this comment

Uh oh!

GustavoStingelin commented Nov 25, 2025

Uh oh!

caarloshenriq commented Nov 25, 2025

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Copilot AI left a comment

Choose a reason for hiding this comment

Pull request overview

Uh oh!

Uh oh!

GustavoStingelin left a comment

Choose a reason for hiding this comment

Uh oh!

GustavoStingelin Jan 3, 2026

Choose a reason for hiding this comment

Uh oh!

GustavoStingelin Jan 3, 2026

Choose a reason for hiding this comment

Uh oh!

GustavoStingelin Jan 3, 2026

Choose a reason for hiding this comment

Uh oh!

GustavoStingelin Jan 3, 2026

Choose a reason for hiding this comment

Uh oh!

GustavoStingelin Jan 3, 2026

Choose a reason for hiding this comment

Uh oh!

Copilot AI left a comment

Choose a reason for hiding this comment

Pull request overview

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

3 participants

FelipeNegrelle left a comment •

edited

Loading