Skip to main content

Contributing

Doxicity is an open source project, meaning everyone can use it and contribute to its development. The easiest way to get started contributing is to check out existing issues and discussions on GitHub.

A common misconception about contributing to an open source project is that you need to know how to code. This simply isn’t true. In fact, there are many ways to contribute, and some of the most important contributions come from those who never write a single line of code. Here’s a list of ways you can make a meaningful contribution to the project:

  • Submitting well-written bug reports
  • Submitting feature requests that are within the scope of the project
  • Improving the documentation
  • Responding to users that need help in the community chat or discussion forum
  • Triaging issues on GitHub
  • Being a developer advocate for the project
  • Sponsoring the project financially
  • Writing tests
  • Sharing ideas
  • And, of course, contributing code!

Please take a moment to review these guidelines to make the contribution process as easy as possible for both yourself and the project’s maintainers.

AI-generated Code

As an open source maintainer, I respectfully ask that you refrain from using AI-generated code when contributing to this project. This includes code generated by tools such as GitHub Copilot, even if you make alterations to it afterwards. While some of Copilot’s features are indeed convenient, the ethics surrounding which codebases the AI has been trained on and their corresponding software licenses remain very questionable and have yet to be tested in a legal context.

I realize that one cannot reasonably enforce this any more than one can enforce not copying licensed code from other codebases, nor do I wish to expend energy policing contributors. I would, however, like to avoid all ethical and legal challenges that result from using AI-generated code. As such, I respectfully ask that you refrain from using such tools when contributing to this project. At this time, I will not knowingly accept any code that has been generated in such a manner.

Using the Issue Tracker

The issue tracker is for bug reports, feature requests, and pull requests.

  • Please do not use the issue tracker for personal support requests. Use the discussion forum instead.
  • Please do not derail, hijack, or troll issues. Keep the discussion on topic and be respectful of others.
  • Please do not post comments with ”+1″ or ”👍”. Use reactions instead.
  • Please do use the issue tracker for feature requests, bug reports, and pull requests.

Issues that do not follow these guidelines are subject to closure. There simply aren’t enough resources for the author and contributors to troubleshoot personal support requests.

Feature Requests

Feature requests can be added using the issue tracker.

  • Please do search for an existing request before suggesting a new feature.
  • Please do use the ”👍” reaction to vote for a feature.
  • Please do share substantial use cases and perspective that support new features if they haven’t already been mentioned.
  • Please do not bump, spam, or ping contributors to prioritize your own feature.

If you would like your feature prioritized, please consider sponsoring the project .

Bug Reports

A bug is a demonstrable problem caused by code in the library. Bug reports are an important contribution to the quality of the project. When submitting a bug report, there are a few steps you can take to make sure your issues gets attention quickly.

  • Please do not paste in large blocks of irrelevant code
  • Please do search for an existing issue before creating a new one
  • Please do explain the bug clearly
  • Please do provide a minimal test case that demonstrates the bug (e.g. jsfiddle.net or CodePen )
  • Please do provide additional information, when necessary, to replicate the bug

A minimal test case is critical to a successful bug report. It demonstrates that the bug exists in the library and not in surrounding code. Contributors should be able to understand the bug without studying your code, otherwise they’ll probably move on to another bug.

If you would like your bug prioritized, please consider sponsoring the project .

Pull Requests

To keep the project on track, please consider the following guidelines before submitting a PR.

  • Please do not submit a PR without opening an issue first, especially for non-trivial changes. This may prevent you from doing work that won’t be accepted for various reasons (e.g. someone is already working on it, it’s not a good fit for the project, it needs additional planning, etc.)
  • Please do make sure your PR clearly defines what you’re changing. Even if you feel your changes are obvious, please explain them so other contributors can more easily review your works. PRs without detailed descriptions are subject to closure pending more details.
  • Please do open your PR against the next branch.
  • Please do not edit anything in dist/. These files are generated automatically, so you need to edit the source files instead.

The author reserves the right to reject any PR that’s outside the scope of the project or doesn’t meet code quality standards.

Branches

current - This branch reflects the latest release and powers doxicity.com .

next - This is the branch you should submit pull requests against. It reflects what’s coming in the next release, which can be previewed at next.doxicity.com .

Developing

To set up a local dev environment, fork the repo on GitHub, clone it locally, and install its dependencies.

git clone https://github.com/YOUR_GITHUB_USERNAME/doxicity
cd doxicity
npm install

Once you’ve cloned the repo, here are some commands you might find helpful:

  • npm start - builds Doxicity and rebuilds when the source code changes
  • npm run build - builds Doxicity
  • npm run docs:build - builds the docs
  • npm run docs:dev - builds the docs and launches a live server that reloads as you edit

Additional scripts can be found by inspecting package.json.