@@ -17,6 +17,8 @@ external ReactJS projects developed by the Topcoder community.
1717 - [ Redux Templates] ( #redux-templates )
1818 - [ Utilities] ( #utilities )
1919- [ Development] ( #development )
20+ - [ Local Testing of Library Updates within a Host Project] ( #local-testing-of-library-updates-within-a-host-project )
21+ - [ Library Releases to NPM] ( #library-releases-to-npm )
2022- [ License] ( #license )
2123
2224## Installation
@@ -94,41 +96,57 @@ $ ./node_modules/.bin/topcoder-lib-setup
9496 Webpack bundling process.
9597
9698## Development
97- For convenient development you can link this package into your host package:
98- 1 . Clone [ ` topcoder-react-utils ` ] ( https://github.com/topcoder-platform/topcoder-react-utils )
99- to your machine, and checkout the branch you are going to work with;
100- 2 . Inside ` topcoder-react-utils ` folder:
101- - Install dependencies with ` $ npm install ` ;
102- - Locate ` node_modules/extract-css-chunks-webpack-plugin/index.js ` and
103- inside the ` isChunk(..) ` function (line #358 ) add ` return true; ` statement,
104- so that this function always returns * true* . This step is necessary at
105- the moment, because the check ` chunk instanceof Chunk ` check inside this
106- function does not work as expected when Webpack config is spread across
107- multiple inter-linked packages.
108- - Run the dev build ` $ npm run build:dev ` . It will compile the package, and
109- also will watch for the file changes to automatically re-compile it as
110- necessary.
111- 3 . Inside the host package execute
112- ` $ npm link PATH_TO_TOPCODER_REACT_UTILS_FOLDER ` . It will create a symlink
113- from ` HOST_PACKAGE/node_modules/topcoder-react-utils ` to your local copy of
114- the ` topcoder-react-utils ` package, so that any changes you do there become
115- automatically available to the host package.
116-
117- CI/CD is set up with CircleCI 2.0 for this repo. A commit to any branch, beside
118- ` master ` will trigger testing of the commited code (it will run ` $ npm test ` and
119- ensures that it does not fail). A commit to the protected ` master ` branch (only
120- organization members and repo admins can commit to ` master ` ) will trigger the
121- testing, and, if successful, release of the updated package to the NPM registry.
122-
123- For successful release to NPM you should bump the package version in the
124- ` package.json ` . To do it conveniently you can use ` $ npm version UPDATE_TYPE `
125- command, where ` UPDATE_TYPE ` stays for one of ` patch ` /` minor ` /` major ` to bump up
126- ` 2 ` , ` 1 ` , or ` 0 ` in a sample version number ` v0.1.2 ` . This command will update
127- ` package.json ` and ` package-lock.json ` , and create a new commit and tag in the
128- checked-out Git branch. Mind that ` patch ` updates should not introduce
129- any breaking changes into the codebase! Breaking changes should be done via
130- ` minor ` or ` major ` update, and they should be documented in
131- the [ CHANGELOG] ( CHANGELOG.md ) .
99+
100+ Whenever you are to do any changes in the library, keep in mind the following:
101+
102+ - Different projects rely on this library, the tooling it provides should be as
103+ generic and flexible as possible. When you change existing components, do your
104+ best to keep backward compatibility of the updated components, any changes
105+ that demand updates in the projects relying on the library, must be
106+ documented in the [ changelog] ( CHANGELOG.md ) .
107+
108+ - Rely on unit tests to verify your changes, and prevent regression. Update
109+ existing unit tests to keep up with your changes, and add new unit tests
110+ when necessary.
111+
112+ - For the final testing of your updates within a host project relying on this
113+ lib, see the next section.
114+
115+ - The library use semantic versioning. In case your changes demand any changes
116+ in the project relying on the library, you should release it as a minor
117+ library update (more severe comparing to patch update). Consider to use
118+ a new branch, called after the minor version, and to not merge your changes
119+ into the main ** develop** / ** master** branches until everybody is prepared
120+ for that.
121+
122+ ### Local Testing of Library Updates within a Host Project
123+
124+ To locally test how your library updates work within a host project relying on
125+ the lib (without releasing them to NPM), use
126+ [ ` npm link ` ] ( https://docs.npmjs.com/cli/link.html ) to link local copy of the lib
127+ into the host project, then run ` npm run build:dev:watch ` in the library root to
128+ automatically re-build the lib when you change it, and use the host project to
129+ see the final effect of changes you make.
130+
131+ ### Library Releases to NPM
132+
133+ Continious Integration and Delivery (CI/CD) is set up for this repository with
134+ CircleCI 2.0. Commits to all branches trigger testing of the code with
135+ ` $ npm test ` (it runs linters and unit tests), and also build the library.
136+ CI/CD flow is interrupted in case of any problems.
137+
138+ To release updated library version to NPM do the following:
139+
140+ - Bump library version in ` package.json ` and ` package-lock.json ` by
141+ ` $ npm version UPDATE_TYPE --no-git-tag ` command, where ` UPDATE_TYPE ` should
142+ be one of ` patch ` / ` minor ` / ` major ` to update current version ` x.y.z `
143+ to ` x.y.(z+1) ` / ` x.(y+1).0 ` / ` (x+1).0.0 ` . The ` --no-git-tag ` flag prevents
144+ automatic creation of the Git tag with the same name as the version.
145+
146+ - Tag the commit to be released with the git tag like ` v0.1.2 ` , where ` 0.1.2 ` is
147+ the new version set in the previous step.
148+
149+ - Commit the tag to GitHub repository.
132150
133151## License
134152Topcoder React Utils is [ MIT Licensed] ( LICENSE.md )
0 commit comments