GNOME.org
 

[gjs: 1/5] Add Internship Getting Started documentation


commit add042b9e42c93ab95ede44988275d9bb27f2174
Author: Philip Chimento <philip chimento gmail com>
Date:   Fri Jul 23 22:13:15 2021 -0700

    Add Internship Getting Started documentation
    
    Iain from the SpiderMonkey team was kind enough to let me steal from the
    document that Mozilla was distributing to Outreachy interns last year.
    I've adapted it to describe our workflow.
    
    To go with it, I've added a section on how to fork and clone the repo, to
    the Hacking document, which I realized was missing.

 CONTRIBUTING.md                   |   4 ++
 README.md                         |   1 +
 doc/Hacking.md                    |  13 +++-
 doc/Internship-Getting-Started.md | 141 ++++++++++++++++++++++++++++++++++++++
 4 files changed, 158 insertions(+), 1 deletion(-)
---
diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md
index c04cd4d2..cb812a24 100644
--- a/CONTRIBUTING.md
+++ b/CONTRIBUTING.md
@@ -70,6 +70,9 @@ free to leave a comment on there asking for help on how to get started.
 than the Newcomers issues, but many of them still do not require
 in-depth familiarity with GJS.
 
+If you're applying to work on GJS for Outreachy or Summer of Code, see
+our [Internship Getting Started][internship] documentation.
+
 ## How to contribute documentation or tutorials ##
 
 If you don't have an account on [gitlab.gnome.org], first create one.
@@ -328,6 +331,7 @@ this guide!
 [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
+[internship]: https://gitlab.gnome.org/GNOME/gjs/blob/HEAD/doc/Internship-Getting-Started.md
 [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
diff --git a/README.md b/README.md
index 5ccfd933..e2ed2c9f 100644
--- a/README.md
+++ b/README.md
@@ -64,6 +64,7 @@ a forked version, [Cinnamon].
 ### Documentation
 
 * [Get started](https://gitlab.gnome.org/GNOME/gjs/-/blob/HEAD/doc/Home.md)
+* [Get started - Internship](https://gitlab.gnome.org/GNOME/gjs/blob/HEAD/doc/Internship-Getting-Started.md)
 * [API documentation](https://gjs-docs.gnome.org/)
 
 ### JavaScript & SpiderMonkey
diff --git a/doc/Hacking.md b/doc/Hacking.md
index 7146e64b..d5648cf8 100644
--- a/doc/Hacking.md
+++ b/doc/Hacking.md
@@ -13,7 +13,18 @@ regular terminal.
 
 ## Setting up ##
 
-First of all, if you are contributing C++ code, install the handy git
+First of all, download the GJS source code using Git.
+Go to [GJS on GitLab](https://gitlab.gnome.org/GNOME/gjs), and click
+"Fork" near the top right of the page.
+Then, click the "Clone" button that's located a bit under the "Fork"
+button, and click the little clipboard icon next to "Clone with SSH" or
+"Clone with HTTPS", to copy the address to your clipboard.
+Go to your terminal, and type `git clone` and then paste the address
+into your terminal with Shift+Ctrl+V.
+(Don't forget Shift! It's important when pasting into a terminal.)
+This will download the GJS source code into a `gjs` directory.
+
+If you are contributing C++ code, install the handy git
 commit hook that will autoformat your code when you commit it.
 In your `gjs` directory, run
 `tools/git-pre-commit-format install`.
diff --git a/doc/Internship-Getting-Started.md b/doc/Internship-Getting-Started.md
new file mode 100644
index 00000000..01d9f0f7
--- /dev/null
+++ b/doc/Internship-Getting-Started.md
@@ -0,0 +1,141 @@
+# Welcome to GJS!
+
+This document is a guide to getting started with GJS, especially if you
+are applying to an internship program such as Outreachy or Summer of
+Code where you make a contribution as part of your application process.
+
+GJS is the JavaScript environment inside GNOME.
+It's responsible for executing the user interface code in the GNOME
+desktop, including the extensions that people use to modify their
+desktop with.
+It's also the environment that several GNOME apps are written in, like
+GNOME Sound Recorder, Polari, etc.
+GJS is written in both C++ and JavaScript, and is built on top of the
+JavaScript engine from Firefox, called SpiderMonkey.
+
+The application process is supposed to give you the opportunity to work
+on good newcomer bugs from GJS.
+
+> Thanks to Iain Ireland for kind permission to adapt this document from
+> SpiderMonkey's instructions!
+
+## Steps to participate
+
+### Phase 1: Getting set up
+
+There are two parts of this phase: getting your development environment
+set up, and getting set up to communicate with the other GNOME
+volunteers.
+For your development environment, the tasks are:
+
+1. Make an account on [GitLab](https://gitlab.gnome.org).
+1. Download the GJS source code and build GJS.
+    > You can follow the [GNOME Newcomer
+    > instructions](https://wiki.gnome.org/Newcomers/BuildProject) if
+    > you want to use Builder, or follow the [instructions](Hacking.md)
+    > for the command line.
+1. Run the GJS test suite and make sure it passes.
+    > Run `meson test -C _build`.
+    > If you are using Builder, do this in a runtime terminal
+    > (Ctrl+Alt+T).
+
+For communication, your tasks are:
+
+1. Create an account on [Matrix](https://gnome.element.io).
+1. Introduce yourself in
+   [#javascript](https://matrix.to/#/#javascript:gnome.org)!
+
+Congratulations! Now you’re ready to contribute!
+
+### Phase 2: Fixing your first bug
+
+1. Find an unclaimed ["Newcomers" bug in the GJS
+   bugtracker](https://gitlab.gnome.org/GNOME/gjs/-/issues?label_name%5B%5D=4.+Newcomers).
+1. Post a comment on your bug to say that you're working on it.
+    > If you're an Outreachy or Summer of Code participant, make sure to
+    > mention that!
+
+    > Please only claim bugs if you are actively working on them.
+    > We have a limited number of newcomers bugs.
+1. Work on the bug.
+1. If you get stuck, ask questions in Matrix or as a comment on the bug.
+   See below for advice on asking good questions.
+1. Once your patch is complete and passes all the tests, make a merge
+   request with GitLab.
+1. If any CI results on the merge request are failing, look at the error
+   logs and make the necessary changes to turn them green.
+    > If this happens, it's usually due to formatting errors.
+1. The project mentor, and maybe others as well, will review the code.
+   Work with them to polish up the patch and get it ready to merge.
+   When it's done, the mentor will merge it.
+    > It's normal to have a few rounds of review.
+
+Congratulations! You've contributed to GNOME!
+
+### Phase 3: Further contributions
+
+If you are applying to an internship and would like to boost your
+application with additional contributions, you can find another bug and
+start the process again.
+
+We're doing our best to make sure that we have enough newcomers bugs
+available for our applicants, but they tend to get fixed quickly during
+the internship application periods.
+If you've already completed an easier bug, please pick a slightly harder
+bug for your next contribution.
+
+## Evaluation dimensions
+
+We **will** be evaluating applicants based on the following criteria:
+
+1. **Communication:** When collaborating remotely, communication is
+   critical.
+   Does the applicant ask good questions?
+   Does the applicant write good comments?
+   Can the applicant clearly explain any challenges they are facing?
+1. **Learning on the fly:** How quickly can the applicant ramp up on a
+   new topic?
+   Is the applicant willing to sit with and struggle through challenging
+   technical problems?
+1. **Programming knowledge:** You don't have to be a wizard, but you
+   should feel reasonably comfortable with programming in the languages
+   that will be mainly used during the project.
+   Is the applicant able to reliably produce merge requests that pass CI
+   with moderate feedback?
+   Does the applicant have a basic understanding of how to debug
+   problems?
+
+We **will not** be evaluating applicants based on the following
+criteria:
+
+1. **Geographic location:** GNOME contributors come from everywhere, and
+   we regularly collaborate across significant time zone gaps.
+   Communication may have to be more asynchronous for applicants in some
+   time zones, but we will not be making a decision based on location.
+1. **Formal qualifications / schooling**: We will be evaluating
+   applicants only based on their contributions during the application
+   process.
+
+## Asking good questions
+
+[This blog post by Julia Evans](https://jvns.ca/blog/good-questions/) is
+an excellent resource on asking good questions.
+(The "decide who to ask" section is less relevant in the context of
+Outreachy or Summer of Code; during the application process, you should
+generally be asking questions in Matrix, and whoever sees your question
+first and knows the answer will respond.)
+
+Good questions should respect the time of both the person answering the
+question, **and the person asking it** (you yourself!).
+You shouldn't flood the Matrix channel asking questions that you could
+answer yourself in a short time with a search engine.
+On the other hand, you should also not spend days trying to figure out
+the answer to something that somebody more experienced could clear up in
+a few minutes.
+
+If you are having problems, it is often useful to take a break and come
+back with a fresh head.
+If you're still stuck, it's amazing how often the answer will come to
+you as you try to write your question down.
+If you've managed to write out a clear statement of your problem, and
+you still can't figure out the answer: ask!
[Date Prev][Date Next]   [Thread Prev][Thread Next]   [Thread Index] [Date Index] [Author Index]