|
| 1 | +# Contributing to Jenkins-Std-Lib |
| 2 | + |
| 3 | +A big welcome and thank you for considering contributing to DontShaveTheYak (dsty) open source projects! It’s people like you that help reduce [Yak Shaving](https://seths.blog/2005/03/dont_shave_that/) in the DevOps community. |
| 4 | + |
| 5 | +Reading and following these guidelines will help us make the contribution process easy and effective for everyone involved. It also communicates that you agree to respect the time of the developers managing and developing these open source projects. In return, we will reciprocate that respect by addressing your issue, assessing changes, and helping you finalize your pull requests. |
| 6 | + |
| 7 | +## Getting Started |
| 8 | + |
| 9 | +Contributions are made to this repo via Issues and Pull Requests (PRs). A few general guidelines that cover both: |
| 10 | + |
| 11 | +- Search for existing Issues and PRs before creating your own. |
| 12 | +- We work hard to makes sure issues are handled in a timely manner but, depending on the impact, it could take a while to investigate the root cause. A friendly ping in the comment thread to the submitter or a contributor can help draw attention if your issue is blocking. |
| 13 | + |
| 14 | +### Issues |
| 15 | + |
| 16 | +Issues should be used to report problems with the library, request a new feature, or to discuss potential changes before a PR is created. |
| 17 | + |
| 18 | +If you find an Issue that addresses the problem you're having, please add your own reproduction information to the existing issue rather than creating a new one. Adding a [reaction](https://github.blog/2016-03-10-add-reactions-to-pull-requests-issues-and-comments/) can also help be indicating to our maintainers that a particular problem is affecting more than just the reporter. |
| 19 | + |
| 20 | +### Pull Requests |
| 21 | + |
| 22 | +PRs to our libraries are always welcome and can be a quick way to get your fix or improvement slated for the next release. In general, PRs should: |
| 23 | + |
| 24 | +- Only fix/add the functionality in question **OR** address wide-spread whitespace/style issues, not both. |
| 25 | +- Add unit or integration tests for fixed or changed functionality (if a test suite already exists). |
| 26 | +- Address a single concern in the least number of changed lines as possible. |
| 27 | +- Include javadoc documentation in the repo. |
| 28 | + |
| 29 | +In general, we follow the ["fork-and-pull" Git workflow](https://github.com/susam/gitpr) |
| 30 | + |
| 31 | +1. Fork the repository to your own Github account |
| 32 | +2. Clone the project to your machine |
| 33 | +3. Create a branch locally with a succinct but descriptive name |
| 34 | +4. Commit changes to the branch |
| 35 | +5. Following any formatting and testing guidelines specific to this repo |
| 36 | +6. Push changes to your fork |
| 37 | +7. Open a PR in our repository so that we can efficiently review the changes. |
| 38 | + |
| 39 | +### Code Style |
| 40 | +We are using GroovyLint to create a consistent experience when reading code. Besides GroovyLint we also ask that Class contructors only take a single argument and thats the workflow script. If you need additional aruguments for your class please use a property/field instead. We prefer this because when using our library to create jobs the user will almost never have autocompletion and groovy has poor support for keyword arguments. |
| 41 | + |
| 42 | +Example: |
| 43 | +```groovy |
| 44 | +// Don't do this |
| 45 | +def myBook = new Book(this, 'A guide to Jenkins', 15) |
| 46 | +
|
| 47 | +// Do this |
| 48 | +def myBook = new Book(this) |
| 49 | +myBook.title = 'A guide to Jenkins' |
| 50 | +myBook.chapters = 15 |
| 51 | +
|
| 52 | +// This might also be okay but usually only in methods |
| 53 | +def myBook = new Book(this, title: 'A guide to Jenkins', chapters: 15) |
| 54 | +``` |
| 55 | + |
| 56 | +### Setup |
| 57 | +The testing of this library is a little quirky. We currently test the library by creating Jenkins jobs in the [jobs](./jobs) folder. The format is `jobs/${packageName}/${className}_example.groovy` and this serves a basic example for users on how to use the class. You can also create unit tests using this format `jobs/${packageName}/tests/test_${className}.groovy` |
| 58 | + |
| 59 | +We then use pytest to call a docker image that will run the jenkins job and return the output of the job. Pytest files use the following format `tests/test_${packageName}/test_${className}.py` |
| 60 | + |
| 61 | +#### Development environment |
| 62 | +1. Have python (we use 3.9) installed and you should probably setup a venv. [Pyenv Guide](https://switowski.com/blog/pyenv) |
| 63 | +2. Install the python requirements. |
| 64 | + ``` |
| 65 | + python -m pip install tests/requirements.txt |
| 66 | + ``` |
| 67 | +3. Install pre-commit hooks. |
| 68 | + ``` |
| 69 | + pre-commit install |
| 70 | + ``` |
| 71 | +4. Run pre-commit to test everything is setup correctly. |
| 72 | + ``` |
| 73 | + pre-commit run --all-files |
| 74 | + ``` |
| 75 | +5. Make your changes and add or update tests. |
| 76 | +6. Run pytest |
| 77 | + ``` |
| 78 | + pytest -s |
| 79 | + ``` |
| 80 | +7. Once all tests are passing commit your changes and open a PR. |
| 81 | +
|
| 82 | +### Custom Test runner |
| 83 | +We use [jenkinsfile-runner](https://github.com/jenkinsci/jenkinsfile-runner) to run our jobs that we use to test this library. The default image is pulled from [dockerhub](https://hub.docker.com/r/shadycuz/jenkins-std-lib) but you can also build it locally. You also might be forced to build it locally if your contribution needs something modified on the Jenkins to run. Such as a plugin or maybe a environment variable. |
| 84 | +
|
| 85 | +#### Building |
| 86 | +From the root of the repo you can run `docker build -t local-runner docker/` but it does take a few miniutes. |
| 87 | +
|
| 88 | +### Using |
| 89 | +To force the use of the local image you can run `CUSTOM_RUNNER=local-runner pytest`. |
0 commit comments