First of all, thanks a lot for at least considering a contribution to approvals-java!
Please keep in mind that all contributions are valuable, and that feedbacks are contributions, so do not hesitate to let us know about your remarks or feelings about the library if you don't feel like doing other things! It's always nice to get feedbacks!
- Getting in touch with the team
- About Approvals-Java
- Environment & Tooling
- Contribution Conventions
- Processes and Operations
- Useful commands
- Development Tips'n'Tricks
Oh, and also, remember our Code of Conduct ;)
There are plently of ways for you to get in touch with us:
- Direct contact with one of us (Twitter, Mail, etc.),
- Creating an issue on Approvals-Java,
- Submitting a Pull Request with changes (even some Work In Progress).
If you'd just like to contribute but don't have much ideas on what to do, feel free to check good first issues or help wanted issues.
Approvals-Java is a pure Java framework with no additional dependencies. That choice has been made to ensure that the library is the easiest possible to integrate in a project and won't lead to conflicts or anything like this.
The framework is dealing a lot with the filesystem and will be used both from developers' workstations and CI servers. Everything should work fine both on Windows & Linux.
It is relying on some Java 8 features, so won't be compliant with earlier Java versions. Further Java versions are to be supported though.
We'd like Approvals-Java to be usable from Scala or Kotlin source code as well, so we're keeping that aspect in mind.
Finally, the library's main goal is to be simple and easy to use, so we want to ensure the documentation and source code are clear and readable.
You can use whatever you want to develop, but here's a list of what we use so you can get some ideas out of it:
Also, we're using those additional tools:
- Gitmoji
- And its IDEA Plugin
- Also this one helps
- editorconfig
- And its IDEA Plugin
- doctoc
- gnupg
- pegdown doclet
- And its IDEA Plugin
- pitest
- Maven License Plugin
And those online services:
- CI jobs should always be green (which means unit tests are ok),
- Shouldn't lower the code coverage,
- Shouldn't lower the marks from CodeClimate,
We're using the default IntelliJ IDEA Java Formatter with those modifications:
- No
<p>is added in Javadoc's empty lines, - Javadoc is wrapped at right margin,
- Written for all packages (
package-info.java), classes, and public functions (at least), - Written in Markdown, (it'll be processed by pegdown doclet)
- Should be updated along with the contributions,
- Should contain examples and code snippets when required,
- Should contain references to latest versions of the library,
- Should have an up-to-date table of contents,
- Make small and independent commits including gitmojis,
- Rebase is preferred to Merge,
- Should follow Semantic Versioning
Most of the actual things to be done from the source code are automated by our Continuous Integration on Travis.
The CI will:
- Build the source code,
- Run the Unit Tests,
- Calculate the code coverage and report it to CodeCov,
- Run quality analysis and report it to CodeClimate
- Create jars for:
- Binaries,
- Source code,
- Javadoc,
- Deploy the jars:
- On oss.jfrog.org for SNAPSHOTs,
- On Bintray for releases.
Releasing a new version of the library is the only action requiring manual operations. To trigger a new release, you have to:
-
Push a commit including a final version in the
pom.xml,./new_tag.sh 0.13.0git push origin v0.13.0
That will trigger the delivery of all necessary jars on Bintray.
Then, you'll have to:
- Create a new release on GitHub,
- Update it with the changelog,
- Synchronize the binaries to Maven Central from Bintray,
- Push a new commit updating the library's version to the next SNAPSHOT.
Please make sure while releasing that you updated properly all necessary documentation and links (everything is located in our README).
We're using the Maven License Plugin to ensure that all of our source code files have a proper license header. The validation will be made in the check phase of the Maven build and will fail it if some files do not contain the proper header.
To update the header in all files, you can run this command:
mvn license:format
From the root of the repository.
We're using doctoc to automagically manage our Markdown documents' table of contents. Do not hesitate to have a look at doctoc's documentation for a complete understanding, but long story short:
Install it with:
npm install -g doctoc
And then update the table of contents of Markdown documents with:
doctoc *.md
Or update a single document with:
doctoc README.md
Ensure that the table of content will be generated in the convenient location by marking that specific place with:
<!-- START doctoc generated TOC please keep comment here to allow auto update -->
<!-- DON'T EDIT THIS SECTION, INSTEAD RE-RUN doctoc TO UPDATE -->
<!-- END doctoc generated TOC please keep comment here to allow auto update -->Our test coverage is calculated by CodeCov, but it doesn't mean all the tests are perfect. To ensure that tests are actually validating properly what the code is supposed to do, you can run mutations on it:
mvn clean test pitest:mutationCoverage
Then have a look at the generated reports.
Once you created a new release on GitHub, you will need to complete that release with the changelog of the current release.
You can get that by executing the provided script at the root of the repository:
./changelog.sh
It will compute the changelog and display it in your terminal. You can then copy/paste it on GitHub.
You should probably instantiate a new CommandReporter in the Windows or Linux (TBC) interface.
Here is a sample syntax:
Reporter IDEA = new CommandReporter(new Command(
"%programFiles%\\JetBrains", "idea64.exe"),
"merge %approved% %received% %approved%");Command will replace %programFiles% with one of the "Program Files" folders on your computer until it finds the executable.
%approved% and %received% are replaced by the file names of the approved and received files.