Skip to content

Commit

Permalink
Made small changes to make the README and CONTRIBUTING files easier t…
Browse files Browse the repository at this point in the history 
…o follow (#4993)

* Made small changes in punctuation, word selection, and word order to make it easier to read and understand the README and CONTRIBUTING 'md' files.

* Made changes based on feedback from @daniel-beck.

* Update README.md

Co-authored-by: Daniel Beck <[email protected]>

* Update CONTRIBUTING.md

Co-authored-by: Mark Waite <[email protected]>

* Apply suggestions from code review

Co-authored-by: Burk Hufnagel <[email protected]>
Co-authored-by: Oleg Nenashev <[email protected]>
Co-authored-by: Daniel Beck <[email protected]>
Co-authored-by: Mark Waite <[email protected]>
  • Loading branch information
@BurkHufnagel @oleg-nenashev
@daniel-beck @MarkEWaite
5 people authored Oct 26, 2020
1 parent 6e14a7e commit 6c9e931
Show file tree
Hide file tree
Showing 2 changed files with 44 additions and 45 deletions.
83 changes: 41 additions & 42 deletions CONTRIBUTING.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -2,58 +2,57 @@

This page provides information about contributing code to the Jenkins core codebase.

:exclamation: There's a lot more to the Jenkins project than just code. For information on contributing to the Jenkins project overall, check out [Participate].
:exclamation: There's a lot more to the Jenkins project than just code. For more information on the ways that you can contribute to the Jenkins project, see [Participate].

## Getting started

1. Fork the repository on GitHub
2. Clone the forked repository to your machine
3. Install the development tools. In order to develop Jenkins, you need the following tools:
3. Install the necessary development tools. In order to develop Jenkins, you need the following:
* Java Development Kit (JDK) 8 or 11.
In Jenkins project we usually use [OpenJDK](http://openjdk.java.net/) or [AdoptOpenJDK](https://adoptopenjdk.net/), but you can use other JDKs as well.
In the Jenkins project we usually use [OpenJDK](http://openjdk.java.net/) or [AdoptOpenJDK](https://adoptopenjdk.net/), but you can use other JDKs as well.
* For JDK 11 there might be some compatibility issues in developer tools,
please see [this page](https://wiki.jenkins.io/display/JENKINS/Java+11+Developer+Guidelines#Java11DeveloperGuidelines-Knowndevelopertoolsissues) for more info.
If you hit a new issue, please report it with a `java11-devtools-compatibility` label in our issue tracker.
* Maven 3.5.4 or above. You can [download maven].
If you find a new issue, please report it with a `java11-devtools-compatibility` label in our issue tracker.
* Maven 3.5.4 or above. You can [download Maven here].
* Any IDE which supports importing Maven projects.
* Install [NodeJS](https://nodejs.org/en/). **Note:** only needed to work on the frontend assets found on the `war` module.
* Frontend tasks are ran using [yarn](https://yarnpkg.com/lang/en/). Run `npm install -g yarn` to install it.
4. Setup your development environment as described in [Preparing for Plugin Development]
* Install [NodeJS](https://nodejs.org/en/). **Note:** only needed to work on the frontend assets found in the `war` module.
* Frontend tasks are run using [yarn](https://yarnpkg.com/lang/en/). Run `npm install -g yarn` to install it.
4. Set up your development environment as described in [Preparing for Plugin Development]

If you want to contribute to Jenkins or just learn about the project,
If you want to contribute to Jenkins, or just learn about the project,
you can start by fixing some easier issues.
In the Jenkins issue tracker we mark such issues as `newbie-friendly`.
You can find them
using this query for [newbie friendly issues].
You can find them by using this query (check the link) for [newbie friendly issues].

## Building and Debugging

The build flow for Jenkins core is built around Maven.
There is a description of the [building and debugging process].
The Jenkins core build flow is built around Maven.
You can read a description of the [building and debugging process here].

If you want simply to have the `jenkins.war` file as fast as possible without tests, run:
If you want simply to build the `jenkins.war` file as fast as possible without tests, run:

```sh
mvn -am -pl war,bom -DskipTests -Dspotbugs.skip clean install
```

The WAR file will be created in `war/target/jenkins.war`.
After that you can start Jenkins using Java CLI ([guide]).
If you want to debug this WAR file without using Maven plugins,
You can just start the executable with [Remote Debug Flags]
After that, you can start Jenkins using Java CLI ([guide]).
If you want to debug the WAR file without using Maven plugins,
You can run the executable with [Remote Debug Flags]
and then attach IDE Debugger to it.

To launch a development instance, after the above command run:
To launch a development instance, after the above command, run:

```sh
mvn -pl war jetty:run
```

(Beware that `maven-plugin` builds will not work in this mode due to class loading conflicts.)
(Beware that `maven-plugin` builds will not work in this mode, due to class loading conflicts.)

### Building frontend assets

To work on the `war` module frontend assets two processes are needed at the same time:
To work on the `war` module frontend assets, two processes are needed at the same time:

On one terminal, start a development server that will not process frontend assets:
```sh
Expand All @@ -69,15 +68,15 @@ cd war; yarn start

Jenkins core includes unit and functional tests as a part of the repository.

Functional tests (`test` module) take a while even on server-grade machines.
Functional tests (`test` module) take a while to run, even on server-grade machines.
Most of the tests will be launched by the continuous integration instance,
so there is no strict need to run full test suites before proposing a pull request.

There are 3 profiles for tests:

* `light-test` - only unit tests, no functional tests
* `smoke-test` - run unit tests + a number of functional tests
* `all-tests` - Runs all tests, with re-run (default)
* `light-test` - runs only unit tests, no functional tests
* `smoke-test` - runs unit tests + a number of functional tests
* `all-tests` - runs all tests, with re-run (default)

In addition to the included tests, you can also find extra integration and UI
tests in the [Acceptance Test Harness (ATH)] repository.
Expand All @@ -93,42 +92,42 @@ cd war; yarn test
## Proposing Changes

The Jenkins project source code repositories are hosted at GitHub.
All proposed changes are submitted and code reviewed using the _GitHub Pull Request_ process.
All proposed changes are submitted, and code reviewed, using the _GitHub Pull Request_ process.

To submit a pull request:

1. Commit changes and push them to your fork on GitHub.
1. Commit your changes and push them to your fork on GitHub.
It is a good practice is to create branches instead of pushing to master.
2. In GitHub Web UI click the _New Pull Request_ button
3. Select `jenkinsci` as _base fork_ and `master` as `base`, then click _Create Pull Request_
* We integrate all changes into the master branch towards the Weekly releases
* After that the changes may be backported to the current LTS baseline by the LTS Team.
Read more about the [backporting process]
2. In the GitHub Web UI, click the _New Pull Request_ button.
3. Select `jenkinsci` as _base fork_ and `master` as `base`, then click _Create Pull Request_.
* We integrate all changes into the master branch towards the Weekly releases.
* After that, the changes may be backported to the current LTS baseline by the LTS Team.
Read more about the [backporting process].
4. Fill in the Pull Request description according to the [proposed template].
5. Click _Create Pull Request_
5. Click _Create Pull Request_.
6. Wait for CI results/reviews, process the feedback.
* If you do not get feedback after 3 days, feel free to ping `@jenkinsci/core-pr-reviewers` in the comments.
* Usually we merge pull requests after 2 approvals from reviewers, no requested changes, and having waited some more time to give others an opportunity to provide more feedback.
See [this page](/docs/MAINTAINERS.adoc) for more information about our review process
* Usually we merge pull requests after 2 approvals from reviewers, no requested changes, and having waited some more time to give others an opportunity to provide their feedback.
See [this page](/docs/MAINTAINERS.adoc) for more information about our review process.

Once your Pull Request is ready to be merged,
the repository maintainers will integrate it, prepare changelogs and
ensure it gets released in one of incoming Weekly releases.
the repository maintainers will integrate it, prepare changelogs, and
ensure it gets released in one of upcoming Weekly releases.
There is no additional action required from pull request authors at this point.

## Copyright

Jenkins core is licensed under [MIT license], with a few exceptions in bundled classes.
The Jenkins core is licensed under [MIT license], with a few exceptions in bundled classes.
We consider all contributions as MIT unless it's explicitly stated otherwise.
MIT-incompatible code contributions will be rejected.
Contributions under MIT-compatible licenses may be also rejected if they are not ultimately necessary.
Contributions under MIT-compatible licenses may also be rejected if they are not ultimately necessary.

We **Do NOT** require pull request submitters to sign the [contributor agreement]
as long as the code is licensed under MIT and merged by one of the contributors with the signed agreement.
as long as the code is licensed under MIT, and merged by one of the contributors with the signed agreement.

We still encourage people to sign the contributor agreement if they intend to submit more than a few pull requests.
Signing is also a mandatory prerequisite for getting merge/push permissions to core repositories
and for joining teams like [Jenkins Security Team].
and for joining teams like the [Jenkins Security Team].

## Continuous Integration

Expand All @@ -147,11 +146,11 @@ just submit a pull request.
* [Beginners Guide To Contributing](https://wiki.jenkins.io/display/JENKINS/Beginners+Guide+to+Contributing)
* [List of newbie-friendly issues in the core](https://issues.jenkins-ci.org/issues/?jql=project%20%3D%20JENKINS%20AND%20status%20in%20(Open%2C%20%22In%20Progress%22%2C%20Reopened)%20AND%20component%20%3D%20core%20AND%20labels%20in%20(newbie-friendly))

[download maven]: https://maven.apache.org/download.cgi
[download Maven]: https://maven.apache.org/download.cgi
[Preparing for Plugin Development]: https://jenkins.io/doc/developer/tutorial/prepare/
[newbie friendly issues]: https://issues.jenkins-ci.org/issues/?jql=project%20%3D%20JENKINS%20AND%20status%20in%20(Open%2C%20%22In%20Progress%22%2C%20Reopened)%20AND%20component%20%3D%20core%20AND%20labels%20in%20(newbie-friendly)
[Participate]: https://jenkins.io/participate/
[building and debugging process]: https://jenkins.io/doc/developer/building/
[building and debugging process here]: https://jenkins.io/doc/developer/building/
[guide]: https://wiki.jenkins.io/display/JENKINS/Starting+and+Accessing+Jenkins
[Remote Debug Flags]: https://stackoverflow.com/questions/975271/remote-debugging-a-java-application
[Acceptance Test Harness (ATH)]: https://github.com/jenkinsci/acceptance-test-harness
Expand Down
6 changes: 3 additions & 3 deletions README.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -8,12 +8,12 @@
[![CII Best Practices](https://bestpractices.coreinfrastructure.org/projects/3538/badge)](https://bestpractices.coreinfrastructure.org/projects/3538)

In a nutshell, Jenkins is the leading open-source automation server.
Built with Java, it provides over 1700 [plugins](https://plugins.jenkins.io/) to support automating virtually anything,
so that humans can actually spend their time doing things machines cannot.
Built with Java, it provides over 1,700 [plugins](https://plugins.jenkins.io/) to support automating virtually anything,
so that humans can spend their time doing things machines cannot.

# What to Use Jenkins for and When to Use It

Use Jenkins to automate your development workflow so you can focus on work that matters most. Jenkins is commonly used for:
Use Jenkins to automate your development workflow, so you can focus on work that matters most. Jenkins is commonly used for:

- Building projects
- Running tests to detect bugs and other issues as soon as they are introduced
Expand Down

0 comments on commit 6c9e931

Please sign in to comment.