Skip to content

Commit

Permalink
Comment and styling cleanup
Browse files Browse the repository at this point in the history 
* Added comments to groovy files
* Ran a markdown linter over our docs
* Ran a spellchecker over both groovy and markdown files

Signed-off-by: Morgan Davies <[email protected]>
  • Loading branch information
Morgan Davies committed Oct 20, 2020
1 parent 5f877ec commit 10fb685
Show file tree
Hide file tree
Showing 20 changed files with 429 additions and 159 deletions.
6 changes: 5 additions & 1 deletion CHANGELOG.md
View file
Original file line number Diff line number Diff line change
@@ -1,4 +1,8 @@
# Changelog for openjdk-build scripts
# Changelog for openjdk-build scripts (DEPRECATED)

## DEPRECATION NOTES

**THIS DOCUMENT IS NO LONGER POPULATED. PLEASE SEE THE [MASTER COMMIT HISTORY](https://github.com/AdoptOpenJDK/openjdk-build/commits/master) FOR A MORE UP TO DATE LOG**

## Version 1.0.0 (14th May 2018)

Expand Down
24 changes: 17 additions & 7 deletions CONTRIBUTING.md
View file
Original file line number Diff line number Diff line change
@@ -1,40 +1,49 @@
# Contributing
You can contribute to this project in many different ways. **We appreciate all kinds of help, so thank you!**

You can contribute to this project in many different ways. **We appreciate all kinds of help, so thank you!**

## Issues and Enhancements

Please let us know via our [issue tracker](https://github.com/AdoptOpenJDK/openjdk-build/issues) if you find a problem, even if you don't have a fix for it. The ideal issue report should be descriptive, and where possible include the steps we can take to reproduce the problem for ourselves.

If you have a proposed fix for an issue, or an enhancement you would like to make to the code please describe it in an issue, then send us the code as a [Github pull request](https://help.github.com/articles/about-pull-requests) as described below.

## Pull requests

We use GitHub's pull requests (PRs) as the primary way to accept contributions to the project. That means we assume you have followed the usual procedure and forked the project repository, cloned your fork, created a new branch for your contribution, and pushed one or more commits to your branch. There are many [on-line guides](https://guides.github.com/activities/forking/) that will help you with these steps.

Consider whether the project documentation or tests also need updating as part of your change, and make that part of the same logical issue and PR. Open your PR against the master branch of the project.

To keep track of [the pull requests we are managing](https://github.com/AdoptOpenJDK/openjdk-build/pulls) we ask that you follow these guidelines for structuring the pull request title and comment.

### Pull request title

Use a descriptive title, and if it relates to an issue in our tracker please reference which one. If the PR is not intended to be merged you should prefix the title with "[WIP]" which indicates it is still Work In Progress. For example, you may wish to send the PR in for an early review as you work through it.

### Pull request comment

The PR comment should be formed by a one-line subject, followed by one line of white space, and one or more descriptive paragraphs, each separated by one line of white space. All of them should be finished by a dot.

Where your PR fixes an issue, it should include a reference to the issue's identifier in the first line of the commit comment. The comment should provide enough information for a reviewer to understand the changes and their relation to the rest of the code.

### Licensing and Developer certificate of origin

When you submit any copyrighted material to the project via a pull request, issue tracker, or any other means, you agree to license the material under [the project's open source license](https://github.com/AdoptOpenJDK/openjdk-build/blob/master/LICENSE), and warrant that you have the legal authority to do so, whether or not you state this explicitly.

We ask that you include a line similar to the following as part of your pull request comment or individual commit comments:
```

```git
DCO 1.1 Signed-off-by: Random J Developer
```

“DCO” stands for “Developer Certificate of Origin,” and refers to [the same text used in the Linux Kernel community](https://elinux.org/Developer_Certificate_Of_Origin). Of course, you should replace "Random J Developer" by your own real name.

By adding this simple comment, you are telling the community that you wrote the code you are contributing, or you have the right to pass on the code that you are contributing.

> Tip: You can use `git commit -s ...` or configure a git `commit.template` to include the sign-off statement in your commit messages automatically.
### Source file headers

All the project's source files must start with a comment, as near to the top of the file as practical, that includes a reference to [the project license](https://github.com/AdoptOpenJDK/openjdk-build/blob/master/LICENSE). Take a look at some existing files to see how we do that, and if there are any questions just ask. In some cases, such as small, trivial files, or source files generated by tooling we don't reference the license again, but it still applies wherever the file contains copyrightable material.

We don't place explicit copyright statements in the project source files. The project comprises many distinct pieces of code, spread across numerous source files, and authored by a variety of individuals. Managing copyright statements is unproductive and [can lead to confusion and contention around the edge cases](https://opensource.com/law/14/n2/copyright-statements-source-files). Rather we utilize [the NOTICE file](https://github.com/AdoptOpenJDK/openjdk-build/blob/master/NOTICE) mechanism as a way to acknowledge copyright broadly where there is a valid reason to do so.
Expand All @@ -43,13 +52,15 @@ Finally, for similar reasons to avoiding individual copyright statements, we don

### Ensuring high quality

If you're changing a shellscript, please make sure you run `./shellcheck.sh` before submitting your PR.
If you're changing a shellscript, please make sure you run `./shellcheck.sh` before submitting your PR. This will also run in a GitHub check titled `Linter / Shellcheck` to ensure you comply to our coding style guidelines.

After we receive your pull request the [Travis pull request builder](https://travis-ci.org/AdoptOpenJDK/openjdk-build) will test your changes and ensure they meet the coding style guidelines. Watch for the results posted as a comment to the PR, and investigate and fix any failures.
After we receive your pull request our [GitHub Checks](https://github.com/AdoptOpenJDK/openjdk-build/tree/master/.github/workflows) will test your changes.
If you're making any changes to our groovy files, you'll be more interested in our [pr-tester](https://ci.adoptopenjdk.net/view/build-tester/job/build-scripts-pr-tester/job/openjdk-build-pr-tester/) jenkins job which executes a set of test pipelines in a semi-live environment (See the [README.md in prTester/](pipelines/build/prTester/README.md) for more information on that). Watch for the results posted as a comment to the PR, investigate and fix any failures.

Fixes can simply be pushed to the same branch from which you opened your pull request. Travis will automatically re-test when new commits are pushed and update the results.
Fixes can simply be pushed to the same branch from which you opened your pull request. GitHub will automatically re-test when new commits are pushed and update the results.

### Reviews and merge conflicts

After your PR has passed the automated testing it will be reviewed by other developers. Comments on the changes and suggested modifications are encouraged from anybody, especially committers. Please keep all comments focused, polite, and technical.

You may consider seeking explicit feedback from a contributor who has already worked on the code being changed.
Expand All @@ -58,7 +69,6 @@ You may consider seeking explicit feedback from a contributor who has already wo
Any reviewer can indicate that a change looks suitable for merging with a comment such as: “I think this patch looks good” or "this fixes the issue for me"; and we use the [LGTM](https://en.wiktionary.org/wiki/LGTM) convention for indicating the strongest level of technical sign-off on a PR. When a committer comments with "LGTM" they specifically mean “I’ve looked at this patch thoroughly and take as much responsibility as if I wrote it myself”.

Sometimes, other changes will be merged ahead of yours which cause a conflict with your pull request’s changes. The PR cannot be merged until the conflict is resolved. As a PR author it is your responsibility to resolve the conflicts and keep the PR up to date. To facilitiate this, try to be responsive to the review discussion rather than let days pass between replies.
Sometimes, other changes will be merged ahead of yours which cause a conflict with your pull request’s changes. The PR cannot be merged until the conflict is resolved. As a PR author it is your responsibility to resolve the conflicts and keep the PR up to date. To facilitate this, try to be responsive to the review discussion rather than let days pass between replies.

Again, **thank you** for contributing to the project!

33 changes: 17 additions & 16 deletions FAQ.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -7,7 +7,7 @@ repository.
## Access control in this repository

The GitHub teams relevant to this repository are as follows (Note, you
won't necessarily have access to see thse links):
won't necessarily have access to see these links):

- [GetOpenJDK](https://github.com/orgs/AdoptOpenJDK/teams/getopenjdk) - `Triage` level of access which lets you assign issues to people
- [build](https://github.com/orgs/AdoptOpenJDK/teams/build) - `Write` access which lets you approve and merge PRs and run and configure most Jenkins jobs
Expand All @@ -19,9 +19,9 @@ I wrote this diagram partially for my own benefit in [issue 957](https://github.
Note that the "end-user" scripts start at `makejdk-any-platform.sh` and a
diagram of those relationships can be seen [here](https://github.com/AdoptOpenJDK/openjdk-build/blob/master/docs/images/AdoptOpenJDK_Build_Script_Relationships.png)

```
```markdown
J - build-scripts/job/utils/job/build-pipeline-generator
G - Create openjdk*-pipeline jobs from pipelines/jobs/popeline_job_template.groovy
G - Create openjdk*-pipeline jobs from pipelines/jobs/pipeline_job_template.groovy
J - openjdk11-pipeline
G - pipelines/build/openjdk*_pipeline.groovy
G - pipelines/build/common/build_base_file.groovy
Expand Down Expand Up @@ -58,15 +58,15 @@ In terms of compilers, these are what we currently use for each release:

| Version | OS | Compiler |
|---------|---------|----------|
| JDK8 | Linux | GCC 4.8 (HotSpot) GCC 7.6 (OpenJ9) |
| JDK11+ | Linux | GCC 7.5 |
| JDK8 | Windows | VS2013 (12.0) (HotSpot) or VS2010 (10.0) (OpenJ9) |
| JDK11+ | Windows | VS2017 |
| JDK8/11 | AIX | xlC/C++ 13.1.3 |
| JDK13+ | AIX | xlC/C++ 16.1.0 |
| JDK8 | macos | GCC 4.2.1 (LLVM 2336.11.00 |
| JDK11 | macos | clang-700.1.81 |
| JDK13+ | macos | clang-900.0.39.2 |
| JDK8 | Linux | GCC 4.8 (HotSpot) GCC 7.6 (OpenJ9) |
| JDK11+ | Linux | GCC 7.5 |
| JDK8 | Windows | VS2013 (12.0) (HotSpot) or VS2010 (10.0) (OpenJ9) |
| JDK11+ | Windows | VS2017 |
| JDK8/11 | AIX | xlC/C++ 13.1.3 |
| JDK13+ | AIX | xlC/C++ 16.1.0 |
| JDK8 | macos | GCC 4.2.1 (LLVM 2336.11.00 |
| JDK11 | macos | clang-700.1.81 |
| JDK13+ | macos | clang-900.0.39.2 |

All machines at AdoptOpenJDK are set up using the ansible playbooks from the
[infrastructure](https://github.com/adoptopenjdk/openjdk-infrastructure) repository.
Expand All @@ -75,7 +75,7 @@ All machines at AdoptOpenJDK are set up using the ansible playbooks from the

1. Create the new release repository under GitHub.com/adoptopenjdk (generally `openjdk-jdkxx`)
2. Add the release to the list at [pipeline file](https://github.com/AdoptOpenJDK/openjdk-build/tree/master/pipelines/build)
3. Adjust the PR testing pipline [Example](https://github.com/AdoptOpenJDK/openjdk-build/pull/1394) to use the new release
3. Adjust the PR testing pipeline [Example](https://github.com/AdoptOpenJDK/openjdk-build/pull/1394) to use the new release

## Removing a major release once you've added a new one

Expand All @@ -94,13 +94,14 @@ Unless the last release was an LTS one, you will generally want to remove one of

We perform different builds such as the based openjdk (hotspot), builds from the Eclipse OpenJ9 codebase as well as others such as Corretto and SAPMachine. These alternatives are referred to as build variants.

First you will need to add support into the [pipeline files](https://github.com/AdoptOpenJDK/openjdk-build/tree/master/pipelines/build) as well as any environment-specific change syou need to make in the [platform files](https://github.com/AdoptOpenJDK/openjdk-build/tree/master/build-farm/platform-specific-configurations)
First you will need to add support into the [pipeline files](https://github.com/AdoptOpenJDK/openjdk-build/tree/master/pipelines/build) as well as any environment-specific changes you need to make in the [platform files](https://github.com/AdoptOpenJDK/openjdk-build/tree/master/build-farm/platform-specific-configurations)
For an example, see [this PR where Dragonwell was added](https://github.com/AdoptOpenJDK/openjdk-build/pull/2051/files)
For more information on other changes required, see [this document](https://github.com/AdoptOpenJDK/TSC/wiki/Adding-a-new-build-variant)

## How do I change the parameters, such as configure flags, for a Jenkins build

Either
Either:

- Modify the environment files in [platform-specific-configurations](https://github.com/AdoptOpenJDK/openjdk-build/tree/master/build-farm/platform-specific-configurations)
- Modify the [pipeline files](https://github.com/AdoptOpenJDK/openjdk-build/tree/master/pipelines/build), although this is normally only done for configuration differences such as OpenJ9 Large Heap builds

Expand All @@ -122,6 +123,6 @@ For more information, see the [PR testing documentation](./pipelines/build/prTes

## Which OS levels do we build on?

The operating systems/distributions which we buid or are documented in the
The operating systems/distributions which we build or are documented in the
[openjdk-build wiki](https://github.com/AdoptOpenJDK/openjdk-build/wiki/%5BWIP%5D-Minimum-OS-levels).
Runtime platforms are in our [supported platforms page](https://adoptopenjdk.net/supported_platforms.html).
Loading

0 comments on commit 10fb685

Please sign in to comment.