Contribute to this Site
Bug reports, documentation changes, and feature requests¶
If you would like to contribute your experience with an IBM Cloud Architecture project back to the project in the form of encountered bug reports, necessary documentation changes, or new feature requests, this can be done through the use of the repository's Issues list.
Before opening a new issue, please reference the existing list to make sure a similar or duplicate item does not already exist. Otherwise, please be as explicit as possible when creating the new item and be sure to include the following:
- Bug reports
- Specific Project Version
- Deployment environment
- A minimal, but complete, setup of steps to recreate the problem
- Documentation changes
- URL to existing incorrect or incomplete documentation (either in the project's GitHub repo or external product documentation)
- Updates required to correct current inconsistency
- If possible, a link to a project fork, sample, or workflow to expose the gap in documentation.
- Feature requests
- Complete description of project feature request, including but not limited to, components of the existing project that are impacted, as well as additional components that may need to be created.
- A minimal, but complete, setup of steps to recreate environment necessary to identify the new feature's current gap.
The more explicit and thorough you are in opening GitHub Issues, the more efficient your interaction with the maintainers will be. When creating the GitHub Issue for your bug report, documentation change, or feature request, be sure to add as many relevant labels as necessary (that are defined for that specific project). These will vary by project, but will be helpful to the maintainers in quickly triaging your new GitHub issues.
We really value contributions, and to maximize the impact of code contributions, we request that any contributions follow the guidelines below. If you are new to open source contribution and would like some more pointers or guidance, you may want to check out Your First PR and First Timers Only. These are a few projects that help on-board new contributors to the overall process.
Coding and Pull Requests best practices¶
- Please ensure you follow the coding standard and code formatting used throughout the existing code base.
- This may vary project by project, but any specific diversion from normal language standards will be explicitly noted.
- One feature / bug fix / documentation update per pull request
- Always pull the latest changes from upstream and rebase before creating any pull request.
- New pull requests should be created against the
integrationbranch of the repository, if available.
- This ensures new code is included in full-stack integration tests before being merged into the
- All new features must be accompanied by associated tests.
- Make sure all tests pass locally before submitting a pull request.
- Include tests with every feature enhancement, improve tests with every bug fix
Github and git flow¶
The internet is littered with guides and information on how to use and understand git. However, here's a compact guide that follows the suggested workflow
Fork the desired repo in github.
Clone your repo to your local computer.
Add the upstream repository
Note: Guide for step 1-3 here: forking a repo
Create new development branch off the targeted upstream branch. This will often be
Do your work:
- Write your code
- Write your tests
- Pass your tests locally
- Commit your intermediate changes as you go and as appropriate
Repeat until satisfied
Fetch latest upstream changes (in case other changes had been delivered upstream while you were developing your new feature).
Push the changes to your repository
Create a pull request against the same targeted upstream branch.
Once the pull request has been reviewed, accepted and merged into the main github repository, you should synchronise your remote and local forked github repository
master branch with the upstream master branch. To do so:
Pull to your local forked repository the latest changes upstream (that is, the pull request).
Push those latest upstream changes pulled locally to your remote forked repository.
What happens next?¶
All pull requests will be automatically built and unit tested by travis-ci, when implemented by that specific project.
You can determine if a given project is enabled for travis-ci unit tests by the existence of a
.travis.ymlfile in the root of the repository or branch.
When in use, all travis-ci unit tests must pass completely before any further review or discussion takes place.
The repository maintainer will then inspect the commit and, if accepted, will pull the code into the upstream branch.
- Should a maintainer or reviewer ask for changes to be made to the pull request, these can be made locally and pushed to your forked repository and branch.
- Commits passing this stage will make it into the next release cycle for the given project.