Mailing List: https://groups.google.com/d/forum/yosai
How to Contribute to the Yosai Project
There are many ways you can contribute to the Yosai Project, from bug identification to refactoring, writing extensions or creating integrations. It is important that our working environment be friendly and welcoming to all potential contributors. With that given, you are to abide by some simple guidelines outlined in the Code of Conduct.
Easy Ways to Contribute
The Yosai community has a Google Group. The Community page has more information about that.
If you want to file a bug report, suggest a feature, or ask a code-related
question, please go to the
yosaiproject/yosai repository on GitHub and
create a new Issue. (You
will need a GitHub account (free).) Please
describe the issue clearly, including steps to reproduce when you report a bug.
How to Contribute Code or Documentation
Step 0 - Prepare and Familiarize Yourself
To contribute code or documentation, you need a GitHub account.
Familiarize yourself with Yosai's coding convention, architecture, and documentation including:
Step 1 - Fork yosai on GitHub
In your web browser, go to the Yosai repository on GitHub
and click the
Fork button in the top right corner. This creates a new Git
yosai in your GitHub account.
Step 2 - Clone Your Fork
(This only has to be done once.) In your local terminal, use Git to clone your
yosai repository to your local computer. Also add the original GitHub
yosaiproject/yosai repository as a remote named
upstream (a convention):
git clone firstname.lastname@example.org:your-github-username/yosai.git cd yosai git add upstream email@example.com:yosaiproject/yosai.git
Step 3 - Fetch and Merge the Latest from
Switch to (checkout) the
master branch, locally, fetch
origin , and
merge the just-fetched
git checkout master git fetch origin git merge master
Step 4 - Create a New Branch for Each Bug/Feature
If your new branch is to fix a bug identified in a specific GitHub Issue
ISSNO, then name your new branch
If your new branch is to add a feature requested in a specific GitHub Issue
ISSNO, then name your new branch
Otherwise, please give your new branch a short, descriptive, all-lowercase name.
git checkout -b new-branch-name
Step 5 - Make Edits, git add, git commit
With your new branch checked out locally, make changes or additions to the code or documentation, git add them, and git commit them.
git add new-or-changed-file git commit -m "Short description of new or changed things"
Remember to write tests for new code, including unit (isolated) tests and integrated tests. Target a unit test coverage ratio of 90% tested. Test coverage of less than 90% affected source code will be scrutinized and potentially rejected.
Please run all existing tests to make sure you didn't break something. Tox is provided to help you run tests.
Remember to write or modify documentation to reflect your additions or changes.
Step 6 - Use Rebase to Refresh From Master
You will want to occasionally synchronize your new branch with changes made upstream (i.e. the original repository) by using rebase:
git fetch origin git rebase origin/master
In the unusual circumstance where other people are also working on the same shared remote feature branch, be sure to rebase changes coming from it:
git rebase origin/your-branch-name
At this point solve any conflicts that come from the rebase.
Step 7 - Push Your New Branch and Submit Pull Request
Ensure that you've commited all that you want to include in your pull request. Then push your new branch to origin. If the branch is already set as 'upstream' and your remote is called 'origin', 'git push' is enough.
git push -u origin new-branch-name
Step 8 - Create a Pull Request
Go to the GitHub website and to your remote yosai repository (i.e. something like https://github.com/your-user-name/yosai).
Send the pull request.
Someone will then merge your branch or suggest changes. If we suggest changes,
you won't have to open a new pull request, you can just push new code to the
same branch (on
origin) as you did before creating the pull request.
Step 9 - Perform a Final Rebase Clean-up
After the review is done, perform a final cleanup and scrub of the feature branch commit history.
git rebase -i origin/master
Contributor Code of Conduct
As contributors and maintainers of this project, and in the interest of fostering an open and welcoming community, we pledge to respect all people who contribute to the project.
We are committed to making participation in this project a harassment-free experience for everyone, regardless of level of experience, gender, gender identity and expression, sexual orientation, disability, personal appearance, body size, race, ethnicity, age, religion, or nationality.
Examples of unacceptable behavior by participants include:
- The use of sexualized language or imagery
- Personal attacks
- Trolling or insulting/derogatory comments
- Public or private harassment
- Publishing other's private information, such as physical or electronic addresses, without explicit permission
- Deliberate intimidation
- Other unethical or unprofessional conduct
Project maintainers have the right and responsibility to remove, edit, or reject comments, commits, code, wiki edits, issues, and other contributions that are not aligned to this Code of Conduct, or to ban temporarily or permanently any contributor for other behaviors that they deem inappropriate, threatening, offensive, or harmful.
By adopting this Code of Conduct, project maintainers commit themselves to fairly and consistently applying these principles to every aspect of managing this project. Project maintainers who do not follow or enforce the Code of Conduct may be permanently removed from the project team.
This Code of Conduct applies both within project spaces and in public spaces when an individual is representing the project or its community.
Instances of abusive, harassing, or otherwise unacceptable behavior directed at yourself or another community member may be reported by contacting a project maintainer. All complaints will be reviewed and investigated and will result in a response that is appropriate to the circumstances. Maintainers are obligated to maintain confidentiality with regard to the reporter of an incident.