Refactor contributing.md

contributing.md

@@ -1,124 +1,122 @@
 # Contributing
 
-> This project has a [code of conduct][coc].
-> By interacting with this repository,
-> organization,
-> or community you agree to abide by its terms.
-
 Hi!
 👋
-We’re excited that you’re interested in contributing!
 Take a moment to read the following guidelines.
-And thanks for contributing to **unist** (**syntax-tree**)!
-👏👌✨
-
-If you’re raising an issue,
-please understand that people involved with this project often do so for fun,
-next to their day job;
-you are not entitled to free customer service.
+Thanks for contributing!
 
 ## Contents
 
+* [Expectations](#expectations)
 * [Ecosystem](#ecosystem)
+* [Support](#support)
 * [Contributions](#contributions)
   * [Financial support](#financial-support)
   * [Improve documentation](#improve-documentation)
   * [Improve issues](#improve-issues)
   * [Give feedback on issues](#give-feedback-on-issues)
   * [Write code](#write-code)
-* [Support](#support)
 * [Submitting an issue](#submitting-an-issue)
 * [Submitting a pull request](#submitting-a-pull-request)
 * [Resources](#resources)
 * [License](#license)
 
+## Expectations
+
+This community has a [code of conduct][file-code-of-conduct].
+You must follow it when interacting with the community.
+
+Be respectful and considerate when asking for things.
+You are not entitled to free customer service.
+
+Be friendly!
+Be excellent to each other.
+
 ## Ecosystem
 
-The collective ([unified][]) consists of several organizations and separate
-projects: most of them are tiny,
-and many of them have a utility
-([`mdast-util-to-hast`][mdast-util-to-hast]),
-a plugin ([`remark-rehype`][remark-rehype]),
-and relate to an ecosystem ([`remark`][remark]) and a syntax tree ([mdast][]).
-Try and pick the right place to contribute to so we can help you faster.
+Pick the right place to contribute.
+The collective ([unified][github-unified]) is hundreds of projects in several
+organizations.
+Often there is
+a utility (such as [`mdast-util-to-hast`][github-mdast-util-to-hast]),
+a plugin ([`remark-rehype`][github-remark-rehype]),
+relating to a syntax tree ([mdast][github-mdast])
+and an ecosystem ([`remark`][github-remark]).
+If you are not sure where to contribute,
+you can first ask a question.
+
+## Support
+
+See [`support.md`][file-support] on how to get help.
 
 ## Contributions
 
-There’s several ways to contribute,
-not just by writing code.
+There are several ways to contribute.
 
 ### Financial support
 
-It’s possible to support us financially by becoming a backer or sponsor through
-[Open Collective][collective].
-With this support,
-we can pay for project leadership,
-finance non-coding work,
-or to do fun things for the community like getting stickers for contributors.
-You’ll be helping unified’s maintainers manage and improve existing projects,
-and additionally support our work to develop new and exciting projects,
-such as [micromark][].
+Support our efforts financially.
+Sponsor us on [GitHub][github-sponsors],
+[`thanks.dev`][thanks],
+or [OpenCollective][].
 
 ### Improve documentation
 
-As a user of this project you’re perfect for helping us improve our docs.
-Typo corrections,
-error fixes,
-better explanations,
+Fix that typo.
+As a user you are perfect for helping us improve the docs.
+Better explanations,
 new examples,
 etcetera.
-Anything!
 
 ### Improve issues
 
+Help make issues easier to resolve.
 Some issues lack information,
-aren’t reproducible,
+are not reproducible,
 or are just incorrect.
-Help make them easier to resolve.
 
 ### Give feedback on issues
 
-We’re always looking for more opinions on discussions in the issue tracker.
+Share your perspective.
+We are often looking for more opinions,
+insights,
+and use cases.
 
 ### Write code
 
-Code contributions are very welcome.
-It’s often good to first create an issue to report a bug or suggest a new
-feature before creating a pull request to prevent you from doing unnecessary
-work.
-
-## Support
-
-See [`support.md`][support] on how to get help.
+Contribute a test,
+patch a bug,
+add a feature.
+It’s often good to first create a discussion or an issue before a pull request.
+Perhaps there’s a reason things are the way they are.
+Or there’s an alternative solution.
 
 ## Submitting an issue
 
-* the issue tracker is for issues.
-  See [`support.md`][support] on how to get help.
-* search the issue tracker (including closed issues) before opening a new
-  issue
-* ensure you’re using the latest version of projects
+* see [`support.md`][file-support] for help;
+  the issue tracker is for issues
+* search [discussions][github-search-discussions] and
+  [issues][github-search-issues] before opening something,
+  include links to what you find
+* contribute a failing test if you can
+* use the latest version of projects
 * use a clear and descriptive title
-* include as much information as possible: steps to reproduce the issue,
-  error message,
-  version,
-  operating system,
-  etcetera
+* include as much information as possible
+* be friendly!
 * the more time you put into an issue,
-  the more we will
-* the best issue report is a [failing test][unit-test] proving it
+  the easier it is to help you
 
 ## Submitting a pull request
 
-* non-trivial changes are often best discussed in an issue first,
-  to prevent
-  you from doing unnecessary work
+* non-trivial things are often best discussed first,
+  to prevent you from doing unnecessary work
 * for ambitious tasks,
-  you should try to get your work in front of the community for feedback as
-  soon as possible
-* new features should be accompanied with tests and documentation
-* don’t include unrelated changes
-* lint and test before submitting code by running `$ npm test`
+  try to get your work in front of the community for feedback as soon as
+  possible
+* do one thing and do it well,
+  do not include unrelated changes
+* include tests and documentation
+* run `npm test` to make sure everything’s still fine
 * write a convincing description of why we should land your pull request:
   it’s your job to convince us
 
@@ -132,28 +130,32 @@ See [`support.md`][support] on how to get help.
 ## License
 
 This document has the following license:
-[CC-BY-4.0][license] © [Titus Wormer][author]
+[CC-BY-4.0][creativecommons-by] © [Titus Wormer][wooorm]
+
+[creativecommons-by]: https://creativecommons.org/licenses/by/4.0/
+
+[file-code-of-conduct]: code-of-conduct.md
 
-[license]: https://creativecommons.org/licenses/by/4.0/
+[file-support]: support.md
 
-[author]: http://wooorm.com
+[github-mdast-util-to-hast]: https://github.com/syntax-tree/mdast-util-to-hast
 
-[coc]: https://github.com/syntax-tree/.github/blob/main/code-of-conduct.md
+[github-mdast]: https://github.com/syntax-tree/mdast
 
-[mdast]: https://github.com/syntax-tree/mdast
+[github-remark-rehype]: https://github.com/remarkjs/remark-rehype
 
-[unified]: https://github.com/unifiedjs/unified
+[github-remark]: https://github.com/remarkjs/remark
 
-[remark]: https://github.com/remarkjs/remark
+[github-unified]: https://github.com/unifiedjs/unified
 
-[mdast-util-to-hast]: https://github.com/syntax-tree/mdast-util-to-hast
+[github-search-discussions]: https://github.com/orgs/syntax-tree/discussions
 
-[remark-rehype]: https://github.com/remarkjs/remark-rehype
+[github-search-issues]: https://github.com/search?q=user%3Asyntax-tree&type=issues
 
-[unit-test]: https://twitter.com/sindresorhus/status/579306280495357953
+[github-sponsors]: https://github.com/sponsors/unifiedjs
 
-[collective]: https://opencollective.com/unified
+[opencollective]: https://opencollective.com/unified
 
-[micromark]: https://github.com/micromark/micromark
+[thanks]: https://thanks.dev
 
-[support]: support.md
+[wooorm]: https://wooorm.com

package.json

@@ -1,25 +1,19 @@
 {
-  "name": "github",
-  "private": true,
-  "version": "0.0.0",
-  "description": "Community health files",
-  "license": "CC-BY-4.0",
-  "keywords": [],
-  "repository": "unifiedjs/.github",
-  "bugs": "https://github.com/unifiedjs/.github",
-  "author": "Titus Wormer <[email protected]> (wooorm.com)",
+  "author": "Titus Wormer <[email protected]> (https://wooorm.com)",
+  "bugs": "https://github.com/syntax-tree/.github",
   "contributors": [
-    "Titus Wormer <[email protected]> (wooorm.com)"
+    "Titus Wormer <[email protected]> (https://wooorm.com)"
   ],
+  "description": "Community health files",
   "devDependencies": {
     "remark-cli": "^12.0.0",
     "remark-frontmatter": "^5.0.0",
     "remark-preset-wooorm": "^10.0.0"
   },
-  "scripts": {
-    "format": "remark --frail --quiet --output -- .",
-    "test": "npm run format"
-  },
+  "keywords": [],
+  "license": "CC-BY-4.0",
+  "name": "github",
+  "private": true,
   "remarkConfig": {
     "plugins": [
       "remark-frontmatter",
@@ -29,5 +23,11 @@
         false
       ]
     ]
-  }
+  },
+  "repository": "syntax-tree/.github",
+  "scripts": {
+    "format": "remark --frail --quiet --output -- .",
+    "test": "npm run format"
+  },
+  "version": "0.0.0"
 }

readme.md

@@ -1,71 +1,55 @@
 # `.github`
 
-Community health files for **unist** (**syntax-tree**).
-This repo hosts the [code of conduct][coc],
-a guide on how to get [support][],
-how to [contribute][],
-a [pull request template][pr],
-and [issue templates][issue].
+Community health files for `syntax-tree`.
 
 ## unified
 
-**unist** (**syntax-tree**) is a [unified collective][unified] project.
-Read how it’s governed in [`unifiedjs/collective`][collective].
+This organization is part of **[unified][github-unified]**.
+See [`unifiedjs/collective`][github-collective] on how it’s governed.
 
-## Awesome syntax-tree
+## Awesome `syntax-tree`
 
-For a curated list of awesome syntax-tree,
-unist,
-hast,
-xast,
-mdast,
-and nlcst resources,
-see [awesome syntax-tree][awesome].
+See [`syntax-tree/awesome-syntax-tree`][github-awesome-syntax-tree] for a
+curated list of awesome resources.
+
+## Code of conduct
+
+This community has a [code of conduct][file-code-of-conduct].
+You must follow it when interacting with the community.
 
 ## Support
 
-We’re glad you’re using these projects and we’d love to help.
-Take a look at [`support.md`][support] to find out how to help us help you.
+See [`support.md`][file-support] on how to get help.
 
 ## Contributing
 
-We’re excited that you’re interested in contributing!
-Take a moment to read [`contributing.md`][contribute].
+See [`contributing.md`][file-contributing] on how to contribute.
 
-Ideas for new utilities and tools can be posted in [`syntax-tree/ideas`][ideas].
+## Security
 
-## Code of conduct
-
-This project has a [code of conduct][coc].
-By interacting with this repository,
-organization,
-or community you agree to abide by its terms.
+See [`security.md`][file-security] if you found a security issue.
 
 ## License
 
 This document has the following license:
-[CC-BY-4.0][license] © [Titus Wormer][author].
+[CC-BY-4.0][creativecommons-by] © [Titus Wormer][wooorm].
 
 Other projects may be licensed differently.
 
-[license]: https://creativecommons.org/licenses/by/4.0/
-
-[author]: http://wooorm.com
-
-[coc]: code-of-conduct.md
+[creativecommons-by]: https://creativecommons.org/licenses/by/4.0/
 
-[contribute]: contributing.md
+[file-code-of-conduct]: code-of-conduct.md
 
-[support]: support.md
+[file-contributing]: contributing.md
 
-[awesome]: https://github.com/syntax-tree/awesome-syntax-tree
+[file-security]: security.md
 
-[ideas]: https://github.com/syntax-tree/ideas
+[file-support]: support.md
 
-[pr]: .github/pull-request-template.md
+[github-awesome-syntax-tree]: https://github.com/syntax-tree/awesome-syntax-tree
 
-[issue]: .github/ISSUE_TEMPLATE
+[github-collective]: https://github.com/unifiedjs/collective
 
-[unified]: https://github.com/unifiedjs
+[github-unified]: https://github.com/unifiedjs
 
-[collective]: https://github.com/unifiedjs/collective
+[wooorm]: https://wooorm.com