Skip to content
This repository has been archived by the owner on Apr 26, 2024. It is now read-only.

Latest commit

 

History

History
179 lines (135 loc) · 10.1 KB

README.md

File metadata and controls

179 lines (135 loc) · 10.1 KB
Raw

Udemy's JS tooling related public NPM packages CircleCI Status

This repository has Babel and ESLint related packages used by various Udemy projects. It is owned by @udemy/web-frontend, but everyone is welcome to contribute. Please refer to the Contributing section to learn more.

This repository uses Lerna to manage multiple npm packages. We configured Lerna to use Yarn Workspaces under the hood.

Installation

Refer to each package's Installation section in order to learn how to install each package. There is no top-level installation. Though, eslint-config-udemy-basics and eslint-plugin-udemy are good starting points.

Commands

In order to contribute to this repository, you need to have a basic understanding of Lerna commands. In a nutshell, there are three important commands to know:

  • lerna add: In order to add a new dependency to an existing package's package.json file, you'd run `yarn bin`/lerna add dependency-name --scope=package-name. E.g.:

    $ `yarn bin`/lerna add eslint-plugin-lodash --scope=eslint-config-udemy-website

  • lerna remove is not implemented yet: In order to remove a dependency from an existing package's package.json file, for now you'd run `cd packages/package-name; yarn remove dependency-name`. E.g.:

    $ cd packages/eslint-config-udemy-website
$ yarn remove eslint-plugin-lodash

  • lerna upgrade also doesn't exist: Follow the instructions above to do a remove and then re-add the package.

  • lerna bootstrap: In order to install all of the dependencies for every package, you can simply run `yarn bin`/lerna bootstrap.

  • lerna publish: In order to publish your changes to npm, you can simply run `yarn bin`/lerna publish. It will prompt you for a version number for each package you have changed.

List of available packages

We individually publish all folders inside packages as a separate npm package. These packages are owned by our Udemy npm organization.

Contributing

Install Yarn v1.9.4 globally.

$ npm install -g yarn@1.9.4

Install all dependencies locally.

$ yarn install
$ `yarn bin`/lerna bootstrap

Run tests to verify everything is working.

$ yarn test

Updating an existing package

  1. Create a new branch.
  2. Add any new dependencies to any of the packages via lerna add.
  3. Install all dependencies (see above).
  4. Make your necessary source file changes.
  5. Write your tests if applicable.
  6. Do NOT update version numbers in package.json files (lerna publish does it for you).
  7. Run yarn test to make sure all tests pass.
  8. Commit/push your changes.
  9. Create a pull request against master.
  10. Get your pull request approved by a member of the Web Frontend team.
  11. Merge your pull request.

Publish changed packages

After changed packages are merged into master, you need to publish the package to npm. Note: you need permission to publish to npm and must also be a github admin of the js-tooling repo. All steps must be done on the master branch.

  1. Checkout the master branch on your machine.
  2. Run git fetch origin --tags. This is important for the lerna publish step below, as lerna checks git tags to determine what changed. See https://github.com/lerna/lerna#updated.
  3. Get the latest code from master via git pull origin. This is important for the lerna publish step below. If you have a merge conflict, lerna will fail to automatically push its "Publish" commit.
  4. Run lerna publish in order to publish your changes to npm.
    • If this is your first time running lerna publish, you will be prompted to first run npm adduser. If you don't have an npm account, create one at https://www.npmjs.com/signup, and ping @udemy/web-frontend to add your account to the Udemy npm organization.
    • If lerna publish doesn't pick up your changes (this happens if you had to run npm adduser), you can manually publish a package via e.g. cd packages/eslint-config-udemy-website; npm publish.
  5. Confirm your changes were published to npm by checking the npm website, e.g. https://www.npmjs.com/package/eslint-config-udemy-website.
  6. lerna publish should have created a "Publish" commit, which includes changes to CHANGELOG.md and package.json. See #4a7ba34 for example. Push this commit directly to master. You nee admin privileges to do this.
  7. Go to the repository where you'd use these new package changes.
  8. Update the package.json dependencies to any babel|eslint-*-udemy-* package as necessary.
  9. Run yarn install to install the changes and to be able to start using the package.

You can always reach out to @udemy/web-frontend on the #dev-team-web-frontend Slack channel.

Adding a new package

  1. Get in touch with @udemy/web-frontend on the #dev-team-web-frontend Slack channel to assess the need for a new npm package to avoid any duplicate work.
  2. Once there is consensus, create a new folder under packages folder under the desired npm package name.
  3. Use index.js as the package's main entry point, and tests.js as its entry point for tests.
  4. Make sure package.json has the necessary information, per existing examples.
  5. Make sure the new package has a meaningful README.md and a valid LICENSE file.
  6. Follow the regular pull request and lerna publish flow as described above.
  7. After publishing the package, make sure that everyone in the udemy:developers npm group has read-write permissions for the package: 
    # Grant permissions.
npm access grant read-write udemy:developers <package name>

# Should list everyone in https://www.npmjs.com/settings/udemy/teams/team/developers/users
npm access ls-collaborators <package name>

Writing commit messages

We use Conventional Commits for commit guidelines. The commit message should be structured as follows:

<type>[optional scope]: <description>

[optional body]

[optional footer]

Example

feat: Introduce eslint-config-tester

It is a utility library to write tests for ESLint configurations.

BREAKING CHANGE: Add a line like this if your code results in a breaking change. This will result
in a major version change.

The commit message format is important because these messages are used to create a changelog for each release.

Repairing Lerna

In case things go wrong, you might have to manually repair lerna. Lerna uses tags to keep track of the latest version of packages when doing lerna publish. It compares the current HEAD with the most recently tagged commit to see if there are any changes that should be published.

Lerna tags look like this: package-name@version, as in prettier-config-udemy-website@1.0.7

The HEAD commit of master should be tagged with the most recently published packages. If that's not the case, and you need to manually add Lerna tags, use this git command to create them: git tag {tag} -m {tag}, as in git tag prettier-config-udemy-website@1.0.7 -m prettier-config-udemy-website@1.0.7. This creates an "annotated tag", which Lerna requires.