CONTRIBUTING.md

   1 # Contributing to Factor
   2
   3 The Factor monorepo contains almost all libraries developed in Factor alongside the Factor distribution.
   4 Contributions of any form are welcome.
   5
   6 Contributing to Factor requires a bleeding-edge build. You can clone the repository and follow the [build steps](README.md#building-factor-from-source) to start working on Factor.
   7
   8 If you have any questions beyond the scope of this document, feel free to ask the [community.](https://www.concatenative.org/wiki/view/Factor/Community)
   9
  10 # Bug reports
  11 If you have found a bug in the Factor distribution,
  12 - Kindly search the [existing issues](https://github.com/factor/factor/issues?q=is%3Aissue) for dupes. Check the closed issues as well, since regression can happen.
  13 - Always file bugs with a platform name and architecture, since issues may be constrained to one.
  14 - For bugs, always add a code sample, and a reproducible test case.
  15   - Always paste the text of the snippet and the text from the error that Factor produces. Screenshots are useful, but text is important.
  16   - If the text cannot feasibly fit in a github issue, use the [Factor pastebin](https://paste.factorcode.org/) or a GitHub gist to host your code.
  17 - If you are adding a feature request, provide details on how the feature should be implemented and add links to existing libraries or papers that will aid with implementing the feature.
  18
  19 # Submitting a patch
  20 - Commits must always have vocabulary names prefixed to them. The commit history has many good examples of this.
  21 - All contributions to Factor are mandatorily under the [BSD license](LICENSE.txt). In new vocabularies, you must add a comment stating the same. You can use your real name or your GitHub nickname.
  22   See [this](https://github.com/factor/factor/blob/master/core/alien/alien.factor) for an example.
  23   - If you are fixing a bug, then you can add your name to the copyright section of the vocabulary, adding the current year if necessary.
  24   - If you make substantial changes and want to be included in bugfixes and future direction for the vocabulary, add you name to the vocabulary's AUTHORS.txt as well.
  25 - Do not submit features without creating a feature request first.
  26 - The repository is structured as follows:
  27   - `basis`: Vocabularies which are well-tested, well-documented, and have a wide variety of uses in Factor code.
  28   - `core`: The set of libraries which are most integral for compiling and bootstrapping Factor. **Do not modify core unless it is absolutely necessary.** You will need to re-bootstrap to check your changes.
  29   - `extra`: Vocabularies which are in beta, or do not necessarily belong in the other vocabularies.
  30     - These vocabularies may be unstable or broken.
  31     - Most new vocabulary contributions start.
  32     - Notably, `extra/webapps` contains the code for the [Concatenative Wiki](https://concatenative.org), [Factor pastebin](https://paste.factorcode.org),
  33       [Planet Factor](https://planet.factorcode.org) and many others. You can contribute to them from here.
  34   - `misc`: Code which is not written in Factor, but holds significance to Factor users. Some editor-specific plugins reside here.
  35   - `vm`: Factor C++ VM files.
  36   - `work`: Store your personal work here. You cannot contribute changes made to work, as it is reserved for the user.
  37 - Style guidelines are as follows:
  38   - Factor code is written in small definitions that reference smaller definitions. Keep words as small as possible by factoring out core parts.
  39   - Use 4 spaces of indentation if your definitions take multiple lines.
  40   - Apart from these guidelines, follow the style of the file you are editing.
  41 - If you are making changes to `basis` or `core`, performing the required changes to documentation is mandatory. You can use the words in
  42   [tools.scaffold](https://docs.factorcode.org/content/article-tools.scaffold.html) to generate the basic structure.
  43   - Some words are referenced in other standalone articles. It is highly recommended to mention those in a comment above your word's documentation,
  44     so that the documentation stays consistent on all referenced pages.
  45 - `<PRIVATE` blocks are highly recommended for helper words. They are a leaky abstraction, but they make the documentation tidier.
  46 - Always run `lint` and `help.lint` on your changes before submitting them.