Skip to content
This repository has been archived by the owner on Aug 27, 2021. It is now read-only.

Latest commit

 

History

History
94 lines (45 loc) · 5.28 KB

CONTRIBUTING.md

File metadata and controls

94 lines (45 loc) · 5.28 KB
Raw

Contributing

If looking for help

  • Please use our Slack full of helpful people :)

  • Not sure which issue pick? Please check those labelled as "For newcomers".

Local git configuration

Contributors must configure local repository after cloning by executing the command from jvm-bloggers/.git/config directory:

git config --local include.path ../.gitconfig

This will configure cloned repository according to project standards. Note that it will not alter your global or system git configuration, it will only modify .git/config file located in the cloned root directory. This is required to run checkstyle task properly (required by commit guidelines).

Code formatting

  • Please use code formatters for your IDE (at this moment IntelliJ and Eclipse are supported). Files to import to your IDE are located in /formatters directory. See IDE Configuration tips for details.

  • Avoid reformatting code that is not affected by your changes, this will make diff of your PR much more concise

Effective cooperation tips

  • Before coding please comment on issue that you will be working on it.

  • Tag the issue with the yellow In progress label if you start working on it (collaborators only).

  • Before coding think if you know everything you need and ask for a clarification when you are not sure about something (especially about "functional" requirements)

General coding guidelines

  • Avoid Javadocs where possible. Comments should be used only when REALLY needed, prefer better naming and clean code over bloated Javadocs.

  • @author tag shouldn't be placed in test classes unless class is a utility/helper class and not a pure test class

  • @since is not needed as we do not have public API

  • Always provide a test to your change

  • Avoid one-time variable. If you decide to use it, be prepared to explain the reason behind

  • Wicket html files representing Pages and Components should be placed in src/main/java directory next to corresponding Java classes, other web-related files (css, images, etc.) should land in src/main/resources

Testing

  • We use Spock as a base testing framework

  • Notation for test classes is YourClassNameSpec (example)

  • Notation for test methods is def "Should do something" (example)

  • Each section after label given/when/then should have indentation one level deeper than label itself

  • Do not use def for local variables declaration in .groovy files, we use static typing instead

  • Object under test should be marked with @Subject annotation from Spock

Liquibase guidelines

  • Do not modify old changesets, always create new one.

  • Always define primary/foreign key names and unique constraint names directly. Use dedicated tags on column definition, or refactor changes.

  • Use patterns below for constraint names:

    • For primary keys: pk_{tableName} (eg. pk_blog, pk_email)
    • For foreign keys: {tableName}_to_{refTableName} (eg. click_to_blog_post)
    • For unique: {tableName}_{columnName}_unique (eg. blog_post_url_unique)

  • Make sure that after renaming a table or column, you've renamed all corresponding constraint names or primary/foreign key names. This additional effort will keep good readability.

Commit guidelines

  • Do not forget to run ./gradlew check before the commit. Green unit tests under IDE (or ./gradlew test) does not guarantee the commit will pass CI. check task will additionally (among unit tests) run checkstyle plugin against source code base.

  • Try to add issue number in each commit message Adds new entity class and liquibase script, #123

  • One (preferably last or final) commit should have fixes #123 or closes #123 so after merging Pull Request corresponding issue will be closed by GitHub (see more datails in this article)

Reviewing and merging

  • If code review has been done and the PR has been successfully merged then delete the PR branch using Delete branch button at the bottom of given PR page.

  • After successfull merge the issue given PR referes to should be automatically closed (if you conformed to commit guidelines ealier). If it was not closed automatically by merge commit then close the related issue manually.

  • Finally remove the yellow in progress label from the closed issue (collaborators only).