diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md new file mode 100644 index 0000000..911da79 --- /dev/null +++ b/CONTRIBUTING.md @@ -0,0 +1,114 @@ + + +## Contributing to the project + +You can click the **Fork** button in the upper-right area of the screen to create a copy of this repository in your GitHub account. You can make content contributions in your fork, and when the changes are ready, go to your fork and create a new pull request to send the changes to us. + +After that, a project reviewer will review your PR and provide feedback. + + +## Doc branches + +Before you get started with the authoring work, it's necessary that you understand the different branches to work on. +* **[`main`](https://github.com/openmainframeproject/wg-modernization/tree/main/docs)** - protected branch + +* You can have your own personal branch to work on content for a certain issue or feature. However, be sure to check and remove unused personal branches periodically for easy maintenance. Usually when your branch is merged, you can safely delete it. + +## Site organization and files + +- `/docs/` - Contains the Markdown files for the docs. Customize the order of the docs sidebar in `sidebars.js`. +- `/docusaurus.config.js` - A config file containing the site configuration. +- `/sidebar.js` - Specify the order of documents in the sidebar. If you have a new file to add to the site, modify this file. +- `/src/` - Non-documentation files like pages or custom React components. + - `/src/pages` - Any files within this directory will be converted into a website page. +- `/static/` - Static directory. Any contents inside here will be copied into the root of the final `build` directory. +- `/package.json` - A Docusaurus website is a React app. You can install and use any npm packages you like in them. + +## Running the doc site locally + +### Prerequisites + +You need the following installed locally: + +- [Node.js](https://nodejs.org/en/download/) version >= 12.13.0 or above (which can be checked by running `node -v`). You can use [nvm](https://github.com/nvm-sh/nvm) for managing multiple Node versions on a single machine installed +- [Yarn](https://yarnpkg.com/en/) version >= 1.5 (which can be checked by running `yarn --version`). Yarn is a performant package manager for JavaScript and replaces the `npm` client. It is not strictly necessary but highly encouraged. + +### Procedure + +Before you start, clone this repository and navigate to the directory: + +1. In your local command line interface, navigate to the directory in which you want to create your local copy of this repository. +1. Clone this repository by running the following command: `git clone https://github.com/openmainframeproject/wg-modernization.git` +1. Access the newly-cloned repository by changing directories into it: `cd docs-site` + +Once you have this repository set up locally and are in the `docs-site` directory, you can build and run the docs site locally by following the steps below: + +1. Run the command to install project dependencies: `npm install` +1. Run `npm start` + +Once complete, you can open your browser and view the doc site locally at [http://localhost:3000/](http://localhost:3000/). As you make changes to the source files, the preview build will be triggered automatically, and then you can refresh your browser to see the changes.