Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

docs: updating CONTRIBUTING.md with table of contents and TOC guidance #12372

Merged
merged 2 commits into from
Aug 12, 2024
Merged

docs: updating CONTRIBUTING.md with table of contents and TOC guidance #12372

Changes from 1 commit
Commits
Show all changes
2 commits
Select commit Hold shift + click to select a range
02444bf
docs: updating CONTRIBUTING.md with table of contents and TOC guidance
BigLep Aug 9, 2024
d3a109a
Update CONTRIBUTING.md
BigLep Aug 12, 2024
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
18 changes: 18 additions & 0 deletions CONTRIBUTING.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,7 +1,16 @@
<!-- omit from toc -->
# Contributing to Lotus

Lotus is a universally open project and welcomes contributions of all kinds: code, docs, and more. We appreciate your interest in contributing!

- [Before Contributing](#before-contributing)
- [Implementing Changes](#implementing-changes)
- [PR Title Conventions](#pr-title-conventions)
- [CHANGELOG Management](#changelog-management)
- [Markdown Conventions](#markdown-conventions)
- [Table Of Contents](#table-of-contents)
- [Getting Help](#getting-help)

## Before Contributing

1. If the proposal entails a protocol change, please first submit a [Filecoin Improvement Proposal](https://github.com/filecoin-project/FIPs).
Expand Down Expand Up @@ -43,6 +52,15 @@ If the change does not require a CHANGELOG.md entry, do one of the following:

Note that this is enforced with https://github.com/filecoin-project/lotus/blob/master/.github/workflows/changelog.yml

## Markdown Conventions
We optimize our markdown files for viewing on GitHub. That isn't to say other syntaxes can't be used, but that is the flavor we we focus on and at the minimum don't want to break.

### Table Of Contents
For longer documents, we tend to inline a table of contents (TOC). This is slightly annoying with Markdown on GitHub because the actual table of contents needs to be checked-in rather than just giving a directive to the renderer like []`[[_TOC_]]` on GitLab](https://docs.gitlab.com/ee/user/markdown.html#table-of-contents). (Yes GitHub UI does enable someone to see an auto-generated outline if they click the "outline" button on the top right-hand corner when viewing a Markdown file, but that isn't necessarily obvious to users, requires an extra click, and doesn't enable any customization.)

[There is tooling](https://stackoverflow.com/questions/11948245/markdown-to-create-pages-and-table-of-contents) that can help with auto-generating and updating a TOC and allow customization. Maintainers aren't wedded to a particular format/standard/tool but have gone with [VS Code Markdown All in One](https://marketplace.visualstudio.com/items?itemName=yzhang.markdown-all-in-one) because it has what we needed and is the most popular VS Code plugin for this functionality (at least as of 202408).


BigLep marked this conversation as resolved.
Show resolved Hide resolved
## Getting Help

If you need help with your contribution, please don't hesitate to ask questions in our [discussions](https://github.com/filecoin-project/lotus/discussions) or reach out to [the maintainers](https://github.com/orgs/filecoin-project/teams/lotus-maintainers).
Expand Down
Loading