[gjs: 4/8] docs: Add a contributing guide

[Philip Chimento <pchimento src gnome org>]

commit fd507b01b852d2e8c0a943dd8a453505dfaa821e
Author: Philip Chimento <philip chimento gmail com>
Date:   Wed Oct 24 22:17:18 2018 -0400

    docs: Add a contributing guide
    
    Inspired by https://github.com/nayafia/contributing-template
    
    See #17.

 CONTRIBUTING.md | 328 ++++++++++++++++++++++++++++++++++++++++++++++++++++++++
 doc/Hacking.md  |  42 ++++++--
 2 files changed, 359 insertions(+), 11 deletions(-)
---
diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md
new file mode 100644
index 00000000..a9b1bef4
--- /dev/null
+++ b/CONTRIBUTING.md
@@ -0,0 +1,328 @@
+# Contributing to GJS #
+
+## Introduction ##
+
+Thank you for considering contributing to GJS!
+As with any open source project, we can't make it as good as possible
+without help from you and others.
+
+We do have some guidelines for contributing, set out in this file.
+Following these guidelines helps communicate that you respect the time
+of the developers who work on GJS.
+In return, they should reciprocate that respect in addressing your
+issue, reviewing your work, and helping finalize your merge requests.
+
+### What kinds of contributions we are looking for ###
+
+There are many ways to contribute to GJS, not only writing code.
+We encourage all of them.
+You can write example programs, tutorials, or blog posts; improve the
+documentation; [submit bug reports and feature requests][bugtracker];
+triage existing bug reports; vote on issues with a thumbs-up or
+thumbs-down; or write code which is incorporated into [GJS itself][gjs].
+
+### What kinds of contributions we are not looking for ###
+
+Please don't use the [issue tracker][bugtracker] for support questions.
+Instead, check out the [#javascript][irc] IRC channel on irc.gnome.org.
+You can also try the [javascript-list][mailinglist] mailing list, or
+Stack Overflow.
+
+If you are writing code, please do not submit merge requests that only
+fix linter errors in code that you are not otherwise changing (unless
+you have discussed it in advance with a maintainer on [IRC][irc].)
+
+When writing code or submitting a feature request, make sure to first
+read the section below titled "Roadmap".
+Contributions that run opposite to the roadmap are not likely to be
+accepted.
+
+## Ground Rules ##
+
+Your responsibilities as a contributor:
+
+- Be welcoming and encouraging to newcomers.
+- Conduct yourself professionally; rude, abusive, harrassing, or
+  discriminatory behaviour is not tolerated.
+- For any major changes and enhancements you want to make, first create
+  an issue in the [bugtracker], discuss things transparently, and get
+  community feedback.
+- Ensure all jobs are green on GitLab CI for your merge requests.
+- Your code must pass the tests.
+- Your code must pass the linters; code should not introduce any new
+  linting errors.
+- Your code should not cause any compiler warnings.
+- Add tests for any new functionality you write, and regression tests
+  for any bugs you fix.
+
+## Your First Contribution ##
+
+Unsure where to start?
+
+Try looking through the [issues labeled "Newcomers"][newcomers].
+We try to have these issues contain some step-by-step explanation on how
+a newcomer might approach them.
+If that explanation is missing from an issue marked "Newcomers", feel
+free to leave a comment on there asking for help on how to get started.
+
+[Issues marked "Help Wanted"][helpwanted] may be a bit more involved
+than the Newcomers issues, but many of them still do not require
+in-depth familiarity with GJS.
+
+## How to contribute documentation or tutorials ##
+
+If you don't have an account on [gitlab.gnome.org], first create one.
+
+Some contributions are done in different places than the main GJS
+repository.
+To contribute to the documentation, go to the [DevDocs][devdocs]
+repository.
+To contribute to tutorials, go to [GJS Guide][gjsguide].
+
+Next, read the [workflow guide to contributing to GNOME][workflow].
+(In short, create a fork of the repository, make your changes on a
+branch, push them to your fork, and create a merge request.)
+
+If your contribution fixes an existing issue, please refer to the issue
+in your commit message with `Closes #123` (for issue 123).
+Otherwise, creating a separate issue is not required.
+See the section on "Commit messages" below.
+
+When you submit your merge request, make sure to click "Allow commits
+from contributors with push access".
+This is so that the maintainers can re-run the GitLab CI jobs, since
+there is currently a bug in the infrastructure that makes some of the
+jobs fail unnecessarily.
+
+That's all!
+
+## How to contribute code ##
+
+To contribute code, follow the instructions above for contributing
+documentation.
+There are further instructions for how to set up a development
+environment and install the correct tools for GJS development in the
+[Hacking.md][hacking] file.
+
+## How to report a bug ##
+
+If you don't have an account on [gitlab.gnome.org], first create one.
+Go to the [issue tracker][bugtracker] and click "New issue".
+
+Use the "bug" template when reporting a bug.
+Make sure to answer the questions in the template, as otherwise it might
+make your bug harder to track down.
+
+_If you find a security vulnerability,_ make sure to mark the issue as
+"confidential"!
+
+If in doubt, ask on [IRC][irc] whether you should report a bug about
+something, but generally it's OK to just go ahead.
+
+## How to suggest a feature or enhancement ##
+
+If you find yourself wishing for a feature that doesn't exist in GJS,
+you are probably not alone.
+Open an issue on our [issue tracker][bugtracker] which describes the
+feature you would like to see, why you need it, and how it should work.
+Use the "feature" template for this.
+However, for a new feature, the likelihood that it will be implemented
+goes way up if you or someone else plans to submit a merge request along
+with it.
+
+In cases where you've seen something that needs to be fixed or
+refactored in the code, it's OK not to use a template.
+It's OK to be less rigorous here, since this type of report is usually
+used by people who plan to fix the issue themselves later.
+
+## How to triage bugs ##
+
+You can help the maintainers by examining the existing bug reports in
+the bugtracker and adding instructions to reproduce them, or
+categorizing them with the correct labels.
+
+For bugs that cause a crash (segmentation fault, not just a JS
+exception) use the "1. Crash" label.
+For other bugs, use the "1. Bug" label.
+Feature requests should get the "1. Feature" label.
+Any crashes, or bugs that prevent most or all users from using GJS or
+GNOME Shell, should also get the "To Do" label.
+
+If some information is missing from the bug (for example, you can't
+reproduce it based on their instructions,) add the "2. Needs
+information" label.
+
+Add any topic labels from the "5" group (e.g. "5. Performance") as you
+see fit.
+
+As for reproducer instructions, a small, self-contained JS program that
+exhibits the bug, to be run with the command-line `gjs` interpreter, is
+best.
+Instructions that provide code to be loaded as a GNOME Shell extension
+are less helpful, because they are more tedious to test.
+
+## Code review process ##
+
+Once you have submitted your merge request, a maintainer will review it.
+You should get a first response within a few days.
+Sometimes maintainers are busy; if it's been a week and you've heard
+nothing, feel free to ping the maintainer and ask for an estimate of
+when they might be able to review the merge request.
+
+You might get a review even if some of the GitLab CI jobs have not yet
+succeeded.
+In that case, acceptance of the merge request is contingent on fixing
+whatever needs to be fixed to get all the jobs to turn green.
+
+In general, unless the merge request is very simple, it will not be
+ready to accept immediately.
+You should normally expect one to three rounds of code review, depending
+on the size and complexity of the merge request.
+Be prepared to accept constructive criticism on your code and to work on
+improving it before it's merged; code review comments don't mean it's
+bad.
+
+Contributors with a GNOME developer account have automatic push access
+to the main GJS repository.
+However, even if you have this access, you are still expected to submit
+a merge request and have a GJS maintainer review it.
+The exception to this is if there is an emergency such as GNOME
+Continuous being broken.
+
+## Community ##
+
+For general questions and support, visit the [#javascript][irc] channel
+on irc.gnome.org.
+
+The maintainers are listed in the [DOAP file][doap] in the root of the
+repository.
+
+## Roadmap and Philosophy ##
+
+This section explains what kinds of changes we do and don't intend to
+make in GJS in the future and what direction we intend to take the
+project.
+
+Internally, GJS uses Firefox's Javascript engine, called SpiderMonkey.
+
+First of all, we will not consider switching GJS to use a different
+Javascript engine.
+If you believe that should be done, the best way to make it happen is to
+start a new project, copy GJS's regression test suite, and make sure all
+the tests pass and you can run GNOME Shell with it.
+
+Every year when a new ESR (extended support release) of Firefox appears,
+we try to upgrade GJS to use the accompanying version of SpiderMonkey
+as soon as possible.
+Sometimes upgrading SpiderMonkey requires breaking backwards
+compatibility, and in that case we try to make it as easy as possible
+for existing code to adapt.
+
+Other than the above exception, we avoid all changes that break existing
+code, even if they would be convenient.
+However, it is OK to break compatibility with GJS's documented behaviour
+if in practice the behaviour never actually worked as documented.
+(That happens more often than you might think.)
+
+We also try to avoid surprises for people who are used to modern ES
+standard Javascript, so custom GJS classes should not deviate from the
+behaviour that people would be used to in the standard.
+
+The Node.js ecosystem is quite popular and many Javascript developers
+are accustomed to it.
+In theory, we would like to move in the direction of providing all the
+same facilities as Node.js, but we do not necessarily want to copy the
+exact way things work in Node.js.
+The platforms are different and so the implementations sometimes need to
+be different too.
+
+The module system in GJS should be considered legacy.
+We don't want to make big changes to it or add any features.
+Instead, we want to enable ES6-style imports for the GJS platform.
+
+We do have some overrides for GNOME libraries such as GLib, to make
+their APIs more Javascript-like.
+However, we like to keep these to a minimum, so that GNOME code remains
+straightforward to read if you are used to using the GNOME libraries in
+other programming languages.
+
+GJS was originally written in C, and the current state of the C++ code
+reflects that.
+Gradually, we want to move the code to a more idiomatic C++ style, using
+smart pointer classes such as `GjsAutoChar` to help avoid memory leaks.
+Even farther in the future, we expect the Rust bindings for SpiderMonkey
+to mature as Mozilla's Servo browser engine progresses, and we may
+consider rewriting part or all of GJS in Rust.
+
+We believe in automating as much as possible to prevent human error.
+GJS is a complex program that powers a lot of GNOME, so breakages can be
+have far-reaching effects in other programs.
+We intend to move in the direction of having more static code checking
+in the future.
+We would also like to have more automated integration testing, for
+example trying to start a GNOME Shell session with each new change in
+GJS.
+
+Lastly, changes should in principle be compatible with other platforms
+than only Linux and GNOME.
+Although we don't have automated testing for other platforms, we will
+occasionally build and test things there, and gladly accept
+contributions to fix breakages on other platforms.
+
+## Conventions ##
+
+### Coding style ###
+
+We use the [Google style guide][googlestyle] for C++ code, with a few
+exceptions, 4-space indents being the main one.
+There is a handy git commit hook that will autoformat your code when you
+commit it; see the [Hacking.md][hacking] file.
+
+For C++ coding style concerns that can't be checked with a linter or an
+autoformatter, read the [CPP_Style_Guide.md][cppstyle] file.
+
+For Javascript code, an [ESLint configuration file][eslint] is included
+in the root of the GJS repository.
+This is not integrated with a git commit hook, so you need to manually
+manually sure that all your new code conforms to the style.
+Don't rewrite old code with `eslint --fix` unless you are already
+changing that code for some other reason.
+
+### Commit messages ###
+
+The title of the commit should say what you changed, and the body of the
+commit message should explain why you changed it.
+We look in the commit history quite often to figure out why code was
+written a certain way, so it's important to justify each change so that
+in the future people will realize why it was needed.
+
+For further guidelines about line length and commit messages, read
+[this guide][commitmessages].
+
+If the commit is related to an open issue in the issue tracker, note
+that on the last line of the commit message. For example, `See #153`, or
+`Closes #277` if the issue should be automatically closed when the merge
+request is accepted.
+
+## Thanks ##
+
+Thanks to [@nayafia][contributingtemplate] for the inspiration to write
+this guide!
+
+[gitlab.gnome.org]: https://gitlab.gnome.org
+[bugtracker]: https://gitlab.gnome.org/GNOME/gjs/issues
+[gjs]: https://gitlab.gnome.org/GNOME/gjs
+[irc]: https://riot.im/app/#/room/#_gimpnet_#javascript:matrix.org
+[mailinglist]: https://mail.gnome.org/mailman/listinfo/javascript-list
+[newcomers]: https://gitlab.gnome.org/GNOME/gjs/issues?label_name%5B%5D=4.+Newcomers
+[helpwanted]: https://gitlab.gnome.org/GNOME/gjs/issues?label_name%5B%5D=4.+Help+Wanted
+[devdocs]: https://github.com/ptomato/devdocs
+[gjsguide]: https://gitlab.gnome.org/rockon999/gjs-guide
+[workflow]: https://wiki.gnome.org/GitLab#Using_a_fork_-_Non_GNOME_developer
+[hacking]: https://gitlab.gnome.org/GNOME/gjs/blob/master/doc/Hacking.md
+[doap]: https://gitlab.gnome.org/GNOME/gjs/blob/master/gjs.doap
+[googlestyle]: https://google.github.io/styleguide/cppguide.html
+[cppstyle]: https://gitlab.gnome.org/GNOME/gjs/blob/master/doc/CPP_Style_Guide.md
+[eslint]: https://eslint.org/
+[commitmessages]: https://chris.beams.io/posts/git-commit/
+[contributingtemplate]: https://github.com/nayafia/contributing-template
diff --git a/doc/Hacking.md b/doc/Hacking.md
index 3bea6f6c..ce516169 100644
--- a/doc/Hacking.md
+++ b/doc/Hacking.md
@@ -2,41 +2,61 @@
 
 ## Setting up ##
 
-We use the
-[Google style guide](https://google.github.io/styleguide/cppguide.html)
-for C++ code, with a few exceptions, 4-space indents being the main one.
-There is a handy git commit hook that will autoformat your code when you
-commit it.
+First of all, if you are contributing C++ code, install the handy git
+commit hook that will autoformat your code when you commit it.
 In your GJS checkout directory, run
 `tools/git-pre-commit-format install`.
 For more information, see
 <https://github.com/barisione/clang-format-hooks/>.
+(You can skip this step if it doesn't work for you, but in that case
+you'll need to manually format your code before it gets merged.
+You can also skip this step if you are not writing any C++ code.)
 
 For the time being, we recommend using JHBuild to develop GJS.
 Follow the [instructions from GNOME](https://wiki.gnome.org/HowDoI/Jhbuild) for 
[JHBuild](https://git.gnome.org/browse/jhbuild/).
 
-Even if your system includes a development package for mozjs, we
+GJS requires four other libraries to be installed: GLib, libffi,
+gobject-introspection, and SpiderMonkey (also called "mozjs60" on some
+systems.)
+The readline library is not required, but strongly recommended.
+We recommend installing your system's development packages for libffi
+and readline, and building the others with JHBuild.
+(For example, on Ubuntu these packages are called `libffi-dev` and
+`libreadline-dev`.)
+
+Even if your system includes a development package for SpiderMonkey, we
 recommend building it on JHBuild so that you can enable the debugging
-features. Add this to your JHBuild configuration file:
+features.
+Add this to your JHBuild configuration file (usually
+`~/.config/jhbuildrc`):
 ```python
 module_autogenargs['mozjs60'] = '--enable-debug'
 ```
-
 Make sure it is built first with `jhbuild build mozjs60`, otherwise
 `jhbuild build gjs` will skip it if you have the system package
 installed.
 
-Debugging features in mozjs reduce performance by quite a lot, in
-exchange for performing many runtime checks that can alert you when
-you're not using the JS API correctly.
+These debugging features reduce performance by quite a lot, but they
+will help catch mistakes in the API that could otherwise go unnoticed
+and cause crashes in gnome-shell later on.
 
 ## Making Sure Your Stuff Doesn't Break Anything Else ##
 
+Make your changes in your GJS checkout directory, then run
+`jhbuild make` to build a modified copy of GJS.
+
 Each changeset should ensure that the test suite still passes.
 In fact, each commit should ensure that the test suite still passes,
 though there are some exceptions to this rule.
 You can run the test suite with `jhbuild make check`.
 
+For some contributions, it's a good idea to test your modified version
+of GJS with GNOME Shell.
+For this, build GNOME Shell with `jhbuild build gnome-shell`, and run
+it with `jhbuild run gnome-shell --replace`.
+You need to be logged into an Xorg session, not Wayland, for this to
+work.
+
 ## Debugging ##
 
 Mozilla has some pretty-printers that make debugging JSAPI code easier.