diff --git a/CONTRIBUTING.adoc b/CONTRIBUTING.adoc deleted file mode 100644 index 61ca44bc9e..0000000000 --- a/CONTRIBUTING.adoc +++ /dev/null @@ -1,24 +0,0 @@ -[[contribution-guidelines]] -= Contribution guidelines - -[[filing-issues]] -== Filing issues - -File issues using the standard link:https://github.com/crc-org/crc/issues[GitHub issue tracker] for the repository. -Before you submit a new issue, we recommend that you search the list of issues to see if anyone already submitted a similar issue. - -[[contributing-patches]] -== Contributing patches - -Thank you for your contributions! Please follow this process to submit a patch: - -. Create an issue describing your proposed change to the repository. -.. The repository owners will triage and respond to your issue promptly. -. Fork the repository and create a topic branch. -. Submit a pull request with the proposed changes. -.. The required format for the Git commit message is "Issue # ". - -[[questions]] -== Questions? - -If you run into issues or have any questions about contributions, feel free to ping the CRC developers on IRC at the #codeready channel on Freenode. diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md new file mode 100644 index 0000000000..1fdf93f112 --- /dev/null +++ b/CONTRIBUTING.md @@ -0,0 +1,23 @@ +Contribution guidelines +======================= + +## Filing issues + +File issues using the standard [GitHub issue tracker](https://github.com/crc-org/crc/issues) for the repository. +Before you submit a new issue, we recommend that you search the list of issues to see if anyone already submitted a similar issue. + + +## Contributing patches + +Thank you for your contributions! Please follow this process to submit a patch: + +- Create an issue describing your proposed change to the repository. + - The repository owners will triage and respond to your issue promptly. +- Fork the repository and create a topic branch. +- Submit a pull request with the proposed changes. + - The required format for the Git commit message is "Issue # ". + + +## Questions? + +If you run into issues or have any questions about contributions, feel free to ping the CRC developers on IRC at the #codeready channel on Freenode. diff --git a/README.adoc b/README.adoc deleted file mode 100644 index dc47c95621..0000000000 --- a/README.adoc +++ /dev/null @@ -1,76 +0,0 @@ -= CRC - Runs Containers -:icons: -:toc: macro -:toc-title: -:toclevels: - -toc::[] - -image:https://github.com/crc-org/crc/actions/workflows/make-check.yml/badge.svg?branch=main["main", link="https://github.com/crc-org/crc/actions/workflows/make-check.yml"] -image:https://github.com/crc-org/crc/actions/workflows/macos-installer.yml/badge.svg["macos pkg", link="https://github.com/crc-org/crc/actions/workflows/macos-installer.yml"] -image:https://github.com/crc-org/crc/actions/workflows/make-rpm.yml/badge.svg["rpm", link="https://github.com/crc-org/crc/actions/workflows/make-rpm.yml"] -image:https://github.com/crc-org/crc/actions/workflows/make-check-win.yml/badge.svg["win", link="https://github.com/crc-org/crc/actions/workflows/make-check-win.yml"] - -[[intro-to-crc]] -== Introduction - -`crc` is a tool to run containers. -It manages a local https://github.com/openshift/origin[OpenShift 4.x] cluster, or an https://github.com/openshift/okd[OKD] cluster VM optimized for testing and development purposes. - -If you are looking for a solution for running OpenShift 3.x, you will need tools such as `oc cluster up`, http://github.com/minishift/minishift[Minishift] or https://developers.redhat.com/products/cdk/overview/[CDK]. - -[[usage-data]] -== Usage data - -The first time CRC is run, you will be asked to opt-in to Red Hat's telemetry collection program. - -With your approval, CRC collects pseudonymized usage data and sends it to Red Hat servers to help improve our products and services. -Read our https://developers.redhat.com/article/tool-data-collection[privacy statement] to learn more about it. -For the specific data points being collected, see xref:usage-data.adoc#data-table[Usage data]. - -=== Manually configuring usage data collection - -You can manually change your preference about usage data collection by running `crc config set consent-telemetry ` before the next `crc start`. - -[[documentation]] -== Documentation - -=== Getting CRC - -CRC binaries with an embedded OpenShift disk image can be downloaded from link:https://console.redhat.com/openshift/create/local[this page]. - -=== Using CRC - -The documentation for CRC is currently hosted by GitHub Pages. - -See the link:https://crc-org.github.io/crc/[CRC Getting Started Guide]. - -=== Building the documentation - -You can find the source files for the documentation in the link:./docs[docs] directory. - -To build the formatted documentation, link:https://github.com/containers/libpod/blob/master/install.md[install podman] then use the following: - -```bash -$ git clone https://github.com/crc-org/crc -$ cd crc -$ make build_docs -``` - -This will create a [filename]`docs/build/master.html` file which you can view in your browser. - -=== Developing CRC - -Developers who want to work on CRC should visit the link:./developing.adoc[Developing CRC] document. - -[[community]] -== Community - -Contributions, questions, and comments are all welcomed and encouraged! - -You can reach the community by: - -- Joining the #codeready channel on https://freenode.net/[Freenode IRC] - -If you want to contribute, make sure to follow the link:CONTRIBUTING.adoc[contribution guidelines] -when you open issues or submit pull requests. diff --git a/README.md b/README.md new file mode 100644 index 0000000000..9fa5e6e996 --- /dev/null +++ b/README.md @@ -0,0 +1,63 @@ +CRC - Runs Containers +===================== + +- [Introduction](https://github.com/crc-org/crc#intro-to-crc) +- [Usage data](https://github.com/crc-org/crc#usage-data) +- [Documentation](https://github.com/crc-org/crc#documentation) +- [Community](https://github.com/crc-org/crc#community) + +[![main](https://github.com/crc-org/crc/actions/workflows/make-check.yml/badge.svg?branch=main)](https://github.com/crc-org/crc/actions/workflows/make-check.yml) [![macos pkg](https://github.com/crc-org/crc/actions/workflows/macos-installer.yml/badge.svg)](https://github.com/crc-org/crc/actions/workflows/macos-installer.yml) [![rpm](https://github.com/crc-org/crc/actions/workflows/make-rpm.yml/badge.svg)](https://github.com/crc-org/crc/actions/workflows/make-rpm.yml) [![win](https://github.com/crc-org/crc/actions/workflows/make-check-win.yml/badge.svg)](https://github.com/crc-org/crc/actions/workflows/make-check-win.yml) + + +## Introduction +`crc` is a tool to run containers. It manages a local [OpenShift 4.x](https://github.com/openshift/origin) cluster, or an [OKD](https://github.com/openshift/okd) cluster VM optimized for testing and development purposes. + +If you are looking for a solution for running OpenShift 3.x, you will need tools such as `oc cluster up`, [Minishift](http://github.com/minishift/minishift) or [CDK](https://developers.redhat.com/products/cdk/overview/). + + +## Usage data +The first time CRC is run, you will be asked to opt-in to Red Hat’s telemetry collection program. + +With your approval, CRC collects pseudonymized usage data and sends it to Red Hat servers to help improve our products and services. Read our [privacy statement](https://developers.redhat.com/article/tool-data-collection) to learn more about it. For the specific data points being collected, see [Usage data](https://github.com/crc-org/crc/blob/main/usage-data.adoc#data-table). + + +### Manually configuring usage data collection +You can manually change your preference about usage data collection by running `crc config set consent-telemetry ` before the next `crc start`. + + +## Documentation + +### Getting CRC +CRC binaries with an embedded OpenShift disk image can be downloaded from [this page](https://console.redhat.com/openshift/create/local). + + +### Using CRC +The documentation for CRC is currently hosted by GitHub Pages. + +See the [CRC Getting Started Guide](https://crc-org.github.io/crc/). + +### Building the documentation +You can find the source files for the documentation in the [docs](https://github.com/crc-org/crc/blob/main/docs) directory. + +To build the formatted documentation, [install podman](https://github.com/containers/libpod/blob/master/install.md) then use the following: + +```shell +$ git clone https://github.com/crc-org/crc +$ cd crc +$ make build_docs +``` + +This will create a `docs/build/master.html` file which you can view in your browser. + +### Developing CRC +Developers who want to work on CRC should visit the [Developing CRC](https://github.com/crc-org/crc/blob/main/developing.adoc) document. + +## Community +Contributions, questions, and comments are all welcomed and encouraged! + +You can reach the community by: + +- Joining the #codeready channel on [Freenode IRC](https://freenode.net/) + + +If you want to contribute, make sure to follow the [contribution guidelines](https://github.com/crc-org/crc/blob/main/CONTRIBUTING.md) when you open issues or submit pull requests. \ No newline at end of file diff --git a/developing.adoc b/developing.adoc deleted file mode 100644 index 11ee6758e3..0000000000 --- a/developing.adoc +++ /dev/null @@ -1,193 +0,0 @@ - - -= Developing CRC - -[[developing-overview]] -== Overview - -The following sections describe how to build and test the project. - -[[develop-prerequisites]] -== Prerequisites - -- Git -- Make -- A recent Go distribution (>=1.11) - -[NOTE] -==== -You should be able to develop the project on Linux, Windows, or macOS. -==== - -[[set-up-dev-env]] -== Setting up the development environment - -[[cloning-repository]] -=== Cloning the repository - -Get the sources from GitHub: - ----- -$ git clone https://github.com/crc-org/crc.git ----- - -[NOTE] -==== -Do not keep the source code in your `$GOPATH`, as link:https://github.com/golang/go/wiki/Modules[Go modules] will cause `make` to fail. -==== - -[[dependency-management]] -== Dependency management - -CRC uses link:https://github.com/golang/go/wiki/Modules[Go modules] for dependency management. - -For more information, see the following: - -. link:https://github.com/golang/go/wiki/Modules[Introduction to Go modules] -. link:https://blog.golang.org/using-go-modules[Using Go modules] - -[[compiling-binaries]] -== Compiling the CRC Binary - -In order to compile the crc executable for your local platform, run the following command: - ----- -$ make ----- - -By default, the above command will place the crc executable in the `$GOBIN` path. - -Run the following command to cross-compile the crc executable for many platforms: - ----- -$ make cross ----- - -*Note*: This command will output the cross-compiled crc executable(s) in the `out` directory by default: - ----- -$ tree out/ -out/ -├── linux-amd64 -│   └── crc -├── macos-amd64 -│   └── crc -└── windows-amd64 - └── crc.exe ----- - -[[running-unit-tests]] -== Running unit tests - -To run all unit test use: - -[source,bash] ----- -$ make test ----- - -If you need to update mocks use: - -[source,bash] ----- -$ make generate_mocks ----- - -[[running-e2e-tests]] -== Running e2e tests - -We have automated e2e tests which keep CRC in shape. - -[[intro-to-e2e-testing]] -=== Introduction -End-to-end (e2e) tests borrow code from link:http://github.com/crc-org/clicumber[Clicumber] package to provide basic functionality for testing CLI binaries. This facilitates running commands in a persistent shell instance (`bash`, `tcsh`, `zsh`, Command Prompt, or PowerShell), assert its outputs (standard output, standard error, or exit code), check configuration files, and so on. The general functionality of Clicumber is then extended by CRC specific test code to cover the whole functionality of CRC. - -[[how-to-run-e2e-tests]] -=== How to run - -First, one needs to set the following flags in `Makefile`, under `e2e` target: - -- `--pull-secret-file`: absolute path to your OpenShift pull secret. -- `--bundle-location`: if bundle is embedded, this flag should be set to `--bundle-location=embedded` or not passed at all; if bundle is not embedded, then absolute path to the bundle should be passed. -- `--crc-binary`: if `crc` binary resides in `$GOPATH/bin`, then this flag needs not be passed; otherwise absolute path to the `crc` binary should be passed. - -To start e2e tests, run: -```bash -$ make e2e -``` - -==== How to run only a subset of all e2e tests - -Implicitly, all e2e tests for your operating system are executed. If you want to run only tests from one feature file, you have to override `GODOG_OPTS` environment variable. For example: - -```bash -make e2e GODOG_OPTS="--godog.tags='@basic && @windows'" BUNDLE_LOCATION= PULL_SECRET_FILE= -``` - -Please notice `@basic && @windows`, where `@basic` tag stands for `basic.feature` file and `@windows` tag for e2e tests designed for Windows. - -[[how-to-test-cert-rotation]] -=== How to test cert rotation - -On linux platform first stop the network time sync using: -``` -$ sudo timedatectl set-ntp off -``` - -Set the time 2 month ahead: -``` -$ sudo date -s '2 month' -``` - -Start the crc with `CRC_DEBUG_ENABLE_STOP_NTP=true` set: -``` -$ CRC_DEBUG_ENABLE_STOP_NTP=true crc start -``` - - -[[e2e-test-logs]] -=== Logs - -Test logs can be found in [filename]`test/e2e/out/test-results`. - - -[[making-github-release]] -== Releasing on Github - -=== Releasing using the github actions workflow - -The github actions workflow link:https://github.com/crc-org/crc/actions/workflows/release.yml[`Publish release on github`] creates a draft release and provides a template with all the component versions and the git change log. - -To start the workflow go to the link:https://github.com/crc-org/crc/actions/workflows/release.yml[workflow page] and click on the `Run Workflow` button, make sure to choose the appropriate tag for the release. - -Once the draft release is available, edit it to include the notable changes for the release and press publish to make it public. - -=== Releasing using the `gh-release.sh` script - -In the CRC repository, we have a script link:https://github.com/crc-org/crc/blob/main/gh-release.sh[`gh-release.sh`] which uses the link:https://cli.github.com[`gh`] tool, make sure it is installed. - -Create a markdown file containing a list of the notable changes named `notable_changes.txt` in the same directory as the script. - -An example `notable_changes.txt`: - -[source,bash] ----- -$ cat notable_changes.txt -- Fixes a bug where `oc` binary was not extracted from bundle when using microshift preset [#3581](https://github.com/crc-org/crc/issues/3581) -- Adds 'microshift' as a possible value to the help string of the 'preset' confg option [#3576](https://github.com/crc-org/crc/issues/3576) ----- - -Then run the script from the release tag and follow the prompts, it'll ask for confirmation before pushing the draft release to github. - -[NOTE] -==== -The script will exit with error if it doesn't find a tag starting with `v` in the current git HEAD. -==== - -[source,bash] ----- -$ git checkout v2.18.0 -$ ./gh-release.sh ----- - -Verify the draft release on the releases page and if everything looks good press publish to make the release public.