Angular Athens - 2nd workshop: Contributing to Angular

George Kalpakas | Twitter: https://twitter.com/gkalpakas

Νotes for the "theoretical" part of the 2nd Angular Athens workshop on contributing to Angular (and OSS in general).

Table of contents

• [ ] About open-source software (OSS) and contributing
• [ ] How to contribute
• [ ] Where to contribute
• [ ] Contribution process
  • [ ] Non-PR-based contribution process
  • [ ] PR-based contribution process
• [ ] Contributing during the workshop
  • [ ] Choosing an issue
  • [ ] Working on the different issue types

About open-source software (OSS) and contributing

Good resources on OSS:

• [ ] On all aspects.
• [ ] Specifically on contributing.

_{Back to top}

How to contribute

There are many different ways to contribute to OSS (in general) and the Angular project (in particular), including (but not limited to):

• [ ] Helping others online/offline (StackOverflow, Discord, Gitter, Slack, colleagues, etc.).
• [ ] Creating educational resources (blog posts, presentations, courses, etc.).
• [ ] Responding to GitHub issues (if you know the answer or have additional information that might help).
• [ ] Creating reproductions for bug reports lacking them.
• [ ] Creating issues for docs problems, bug reports, feature requests.
• [ ] Reviewing pull requests (PRs) - esp. if you have expertise on the subject or framework area.
• [ ] Submitting PRs.

For PRs in particular, there can be several types (with varying degrees of complexity):

• [ ] Simple docs fixes (typos, punctuation, grammar, etc.).
• [ ] Docs improvements (re-wording, new content, etc.).
• [ ] Code refactoring (styling fixes, code simplification, etc.).
• [ ] Bug fixes (again, with varying degrees of complexity).
• [ ] New features.

IMPORTANT:
Before spending significant time on a PR, coordinate with the team.

_{Back to top}

Where to contribute

The Angular project comprises several repositories. Choose where to contribute based on your interests:

• [ ] Framework: Most @angular/* packages (such as core, forms, router, animations, etc.).
  This is what we are focusing on in this workshop.
• [ ] CLI: The @angular/cli package and all @angular-devkit/* packages.
• [ ] Universal: All @nguniversal/* packages.
• [ ] Components (aka Material): The @angular/cdk and @angular/material packages (plus some other packages related to CDK/Material).
• [ ] AngularJS material: The angular-material package (i.e. Material design for AngularJS v1.x).
  It will enter LTS mode soon.

_{Back to top}

Contribution process

Non-PR-based contribution process

For contributions that do not involve submitting a PR, the process is simple:

• [ ] Just navigate to the issue on GitHub in your browser.

If you want to create a reproduction for an issue, you have two options:

• [ ] Create a minimal app that reproduces the problem on StackBlitz.
  (Use this template for creating an Angular app.)
• [ ] Create a minimal project that reproduces the problem and push it to a new GitHub repository.

NOTE:
Generally, StackBlitz is preferable as a reproduction medium, but there are some issues that cannot be reproduced on StackBlitz. For example, issues involving ServiceWorkers, server-side rendering, custom build configurations, etc.

_{Back to top}

PR-based contribution process

Below is an overview of the process of creating and submitting a PR. For more details, check out CONTRIBUTING.md.

NOTE:
For simple PRs that only affect a single file (and no tests), one can work directly in their browser and submit a PR using the GitHub UI .

• [ ] 1. Ensure the following tools are installed and available on the PATH:

  • [ ] git (any reasonably recent version) - Download git
  • [ ] Node.js (a version in the range specified in package.json > engines.node) - Download Node.js
  • [ ] yarn (a version in the range specified in package.json > engines.yarn) - Install yarn

• [ ] 2. Fork the angular/angular repo. (instructions)

• [ ] 3. Clone your fork locally. (instructions)

• [ ] 4. Pick an issue to work on.
  For the workshop, you can pick from our curated list.

• [ ] 5. Write one or more failing tests (if applicable).

• [ ] 6. Implement the fix or feature.

• [ ] 7. Submit a PR. (Also sign the CLA if not already signed.)

• [ ] 8. Address any review feedback.

• [ ] 9. :tada:

_{Back to top}

Contributing during the workshop

Choosing an issue

You can freely choose what kind of contribution you want to work on.
(For the workshop, we are sticking to the angular/angular repo.)

Issues labelled as hotlist: community-help are good candidates for contributions from the community.

Since there are currently over 2500 issues on angular/angular (:sweat_smile:), we have put together a curated list of issues that we consider suitable for first-time contributors.

There are basically 4 types of issues on the list:

• [ ] support:

  • These are about interacting on GitHub issues and providing useful information.
  • They do not involve submitting a PR.

• [ ] documentation:

  • These are about fixing issues in documentation content.
  • They involve submitting a PR, but not writing/building code or running tests.

• [ ] docs-infra:

  • These are about fixing issues in the documentation infrastructure, i.e. the angular.io application and related tooling.
  • They may involve writing code and potentially building the app and/or running tests.

• [ ] bug:

  • These are about fixing issues in the framework itself (i.e. one of the @angular/* packages).
  • They involve writing/building code and running tests.

  NOTE: There is currently only one issue of this type, because such issues tend to be more challenging (and thus not suitable for a first-time contributor).

_{Back to top}

Working on the different issue types

Depending on the type of issue, there are different commands one can run to prepare their environment before starting with the actual work.

• [ ] For issues labelled as support: N/A
• [ ] For issues labelled as documentation or docs-infra: yarn --cwd=aio setup
  See also aio/README.md for more info on working on the angular.io application and the documentation content.
• [ ] For issues labelled as bug: yarn install
  See also docs/DEVELOPER.md for more info on working on the Angular source code.

_{Back to top}

:computer: Happy hacking! :rocket: