Welcome! Thank you for contributing to SkoHub.
The following is a set of guidelines for contributing to SkoHub and how to work together in an efficient and goal-oriented way.
We use the simple GitHub workflow: the main branch is always in a working state. New features are developed in feature branches which are merged into main after review in pull requests.
See details on the GitHub flow.
The agile methods we use are inspired by the Scrum Guide.
This section guides you through submitting a bug report for SkoHub. Following these guidelines helps maintainers and the community understand your report, reproduce the behavior and find related reports.
Before creating bug reports, please check if an issue with this bug already exists in the appropriate repository, e.g. SkoHub Vocabs. When you are creating a bug report, please include as many details as possible.
Note: If you find a Closed issue that seems like it is the same thing that you're experiencing, open a new issue and include a link to the original issue in the body of your new one.
Bugs are tracked as GitHub issues. Create a new issue on the appropriate repository, e.g. skohub-vocabs.
Explain the problem and include additional details to help maintainers reproduce the problem:
- Use a clear and descriptive title for the issue to identify the problem.
- Describe the exact steps which reproduce the problem in as many details as possible. For example, start by explaining which SkoHub module you are running and how you run it. When listing steps, don't just say what you did, but explain how you did it. For example, if you're describing the behavior of a SkoHub Vocabs build, provide the actual data and version of SkoHub Vocabs (if possible).
- Provide specific examples to demonstrate the steps. Include links to files or GitHub projects, or copy/pasteable snippets, which you use in those examples. If you're providing snippets in the issue, use Markdown code blocks. The ideal example would be a stripped-down runnable use case using some sample data showing the problematic behavior.
- Describe the behavior you observed after following the steps and point out what exactly is the problem with that behavior.
- Explain which behavior you expected to see instead and why.
- If the problem wasn't triggered by a specific action, describe what you were doing before the problem happened.
This section guides you through submitting an enhancement suggestion for SkoHub, including completely new features and minor improvements to existing functionality. Following these guidelines helps maintainers and the community understand your suggestion and find related suggestions.
Before creating enhancement suggestions, please perform a cursory search to see if the enhancement has already been suggested. If it has, add a comment to the existing issue instead of opening a new one. When you are creating an enhancement suggestion, please include as many details as possible:
Enhancement suggestions are tracked as GitHub issues. Create a new issue on the appropriate repository, e.g. skohub-vocabs.
Provide the following information:
- Use a clear and descriptive title for the issue to identify the suggestion.
- Provide a step-by-step description of the suggested enhancement in as many details as possible.
- Explain why this enhancement would be useful to most users.
- List any other applications where this enhancement exists.
We use, where possible and sensible, a test-driven approach. So please add tests or adjust tests if you are contributing code. In general we favour tests that test behavior rather than implementation details.
The overall code contribution process is:
- Fork the appropriate SkoHub repo and clone your fork (members with write access: clone the appropriate SkoHub repo)
- In your local clone, switch to a new feature branch for the bug fix or feature enhancement you want to implement. The name of the feature branch should start with the corresponding issue number and contain additional info for convenience (using camelCaseFormatting, e.g. '111-featureDesciption')
- Implement, test, and build your bug fix or feature enhancement
- Commit your changes (including tests) and push the feature branch to your fork (members with write access: push to the appropriate SkoHub repo)
- Open a pull request for your feature branch to submit your changes (see details below)
Before submitting your changes, make sure you have added tests for your feature or updated existing tests that were not finding the bug you fixed. All tests should be passing.
Please follow these steps to propose contributions to the project.
When submitting a pull request use a meaningful title and use closing keywords in the pull request description to reference the issue it is meant to resolve. After you submit your pull request, verify that all GitHub Actions are passing. Look at act for testing GitHub Actions locally. If an action is failing, and you believe that the failure is unrelated to your change, please leave a comment on the pull request explaining why you believe the failure is unrelated. If the failure was a false positive, we will open an issue to track that problem with the GitHub Actions.
The reviewer(s) may ask you to complete additional design work, tests, or other changes before your pull request can be ultimately accepted.
Git commits should be as granular as possible. When working on a fix for issue X, we try not to add other things we notice (formatting, refactorings, etc.) to the same commit. Those things should be placed in an own commit to the same branch. Commits should always reference a related issue (like "#111"). This makes each specific change easier to review and understand in the future.
- Use the imperative mood in a subject line ("Add feature" not "Added feature")
- Separate subject from body with a blank line
- Capitalize the subject line
- Do not end the subject line with a period
- Wrap lines at 72 characters
- Use the body to explain what and why not how (which can be seen in the diff)
- Reference issues in the same repository at the end of the first line using the short form (e.g. #14)
As a general rule, we don't change public commit history, i.e. we don’t use --force or -f with git push.
Local amending and rebasing before pushing to GitHub is no problem and will not require to --force when pushing.
While we consider this general rule as directive, we condone force pushing as long as the branch has no open pull request yet and only one person is working on this branch.
In case of a force push we use --force-with-lease to ensure that we do not overwrite any remote commits.
If rewriting is required in an open pull request, instead of force pushing we open a new branch based on main and cherry-pick commits or add new code in this branch.
The existing pull request is then closed.
Please format your code according to the code quality and style guidelines fo the respective SkoHub repository. Some repositories (e.g. SkoHub Vocabs) have automated style and formatting checks that are applied before each commit.
If you notice errors, inconsistencies or missing parts in the documentation, we are very happy about improvements. Please follow the general process for contributing code from above, or open an issue.
We use the SkoHub Board to track the progress of SkoHub issues. In the following we describe when issues are ready and what stages to pass to make a issue done.
Issues move from left to right. We use the following columns:
Here are all issues that are planned but not ready, have open questions and/or dependencies on other issues or on an external resource. As an open community project, we don't want to reject suggestions or requests due to missing resources. At the same time, we can't promise to implement all issues in the backlog.
An issue is ready if it’s possible to start working on it according to the Definition of Ready. Prioritized items (like bugs) are moved to the top of the Ready column. The assignee must re-verify the readiness when moving the item from Ready to Working, especially when an item has been in the 'Ready'-column for a long time.
When we start working on an issue, we move it to the working column. Ideally, every person should only work on one issue at a time. That way the working column provides an overview of who is currently working on what. Issues are only moved into or out of the working column by the person who is assigned. Issues in working are only reassigned by the person who is currently assigned. Such a reassignment may happen if the person responsible for working on the issue changes. If the assignee thinks the issue is ready for review they move it to the Review column, assign the previously announced functional reviewer (see Definition of Ready), and open an pull request for the feature branch. They also add instructions and links in the PR for testing the changed behavior. The assignee of the pull request is the original assignee of the issue together with the functional reviewer. This makes sure that one person is always assigned on the PR and has a focus on the progress. For details, see the above section on contributing code.
There are two kinds of reviews: first, a functional review (which happens on the issue) and second, a code review (which happens on the pull request).
In functional review, the actual behavior of the bugfix or the new feature is reviewed. If the reviewer finds problems, these should be described by providing links, examples, or screenshots that show the behavior. After leaving those comments the reviewer removes their own assignment and lets the person responsible for the issue fix them. After that the reviewer might be reassigned for a new review. If everything works as expected, the reviewer posts a +1 comment on the issue, approves the PR, removes their assignment and adds the suggested code reviewer as assignee and reviewer of the linked pull request.
In code review, the technical implementation of the bugfix or the new feature is reviewed. The reviewer needs to check if tests were implemented that test the new behavior. Changes during the review process are created in additional commits which are pushed to the feature branch. They are added to the existing pull request automatically. At the end of the code review, the reviewer approves the pull request and cancels its assignment.
The creator of the pull request merges the pull request after checking the Definition of Done. After the merge, the issue and the linked pull request are closed and moved to the Done column automatically (due to the closing keywords used in the pull request description). We delete feature branches after merging.
The Definition of Ready describes a list of criteria which issues have to meet to move from column 'Backlog' to 'Ready':
- The person who will implement the issue is assigned and has every information to work on this issue. This includes a detailed description of the bug or the feature that should be implemented. Only the assignee can move the issue to Ready.
- For features: If possible add a small user story, which tells us, how this feature is going to be used. The detailed description should contain a checklist that describes the feature, so that it is clear, when the feature is fully implemented.
- The person who will do code review is mentioned in the issue, e.g. in a comment like "code could be reviewed by ..." (functional review will typically be done by the person reporting the issue when they verify the fix).
- There are no blocking dependencies. Dependencies are expressed through simple referencing of the blocking issue (e.g. depends on #111), see details on autolinked references and URLs.
The Definition of Done describes a list of criteria which issues have to meet to be called 'Done':
- Functionality reviewed (approved by user/product owner)
- Documentation exists (external documentation must be linked)
- GitHub Actions / CI passed (contains tests)
- Pull request is reviewed and approved
- Functionality is merged into the
mainbranch