Skip to content

Latest commit

 

History

History
286 lines (184 loc) · 9.22 KB

CONTRIBUTING.md

File metadata and controls

286 lines (184 loc) · 9.22 KB
Raw

Creator contributor guide.

Reporting issues and bugs.

If you discover a bug, have a technical question for the development team, or find an issue or area that you feel needs improvement:

  • Navigate to the "Issues" tab on the project Github repository
  • Click the "New Issue" button.

When making your report, be as clear and concise as possible. Use the following list as a guide:

  • Describe the issue, and why you believe it's a problem.
  • Include the project version or commit id.
  • Describe environment details (OS/distribution etc).
  • State how often the issue has occurred.
  • Describe the steps to take to uncover or reproduce the issue (if any).
  • Expected behaviour.
  • Actual behaviour.
  • Any additional information, log output etc.

Developer submissions.

If you have a submission for a code change to resolve a bug, improve code implementation, or bring a new feature to the project you should create a Github Pull Request for your submission.

Create a Github account.

Before you can contribute you require a Github account.

You can sign up for a free account here: https://github.com/

Add your ssh key to your Github account.

If you are using a Linux development environment, you can normally find your public key in ~/.ssh/id_rsa.pub. Alternatively you can generate a new key with the following command:

ssh-keygen -t rsa -b 4096 -C "[email protected]"

When you're prompted to enter a file in which to save the key, press Enter to accept the default file location.

Now that you have a key:

  • Sign in to your Github account
  • Click the top right icon
  • Select settings -> ssh keys -> new ssh key
  • Paste the contents of your public key into the box.

Your public key should look something like:

ssh-rsa AAAAB3NzaC1yc2EAAAADAQABAAACAQDOvXIAom7iVB/JmNFZrDNZVz+ta6vZoAvoyzjAR53
LwFyA82TDK4RkosKZHgEU/KT+AXYZ9983uVvzS/O7rxa1YxiL21ckw8Ymm4qRxjMP6Bvw8vsGXlLfq7
bNH2tmxIMxd/csIR246FxmCIddLcrIJ2JOTF3AXNRX8uw0FFeJuZTIkAF/PLDO4HhStY6AGxDzpgoZt
480EdPXzNRqTPJ41iXmMZhsJ3I7HCNeZHmy4VFk0XWKXdvmYKm7nSHeqMZxA9LHRPbLnolJyuBp7qPJ
yWC8xT48dS8PDmn5i/wYyXEBNS6uwsYfLZuPfPAKaSTzd1g1fphEw4/9rTZIqqUSMBR87IdDhVKffvf
tQD4O0TTJAsVEzx6w2dx29lwKWrhuJ9ipSZyH+ujai+azW52b+RmcFOqXh7E79XvWfMF1NqiEDtlqFV
gqnvYg+PkS4+sCyLE0qfMx301r9E6pSTj0SIsBz0PUHFhNUx3grg4eJ1FH8Zu9+JYaFjZeNEFSypxaS
Z7J6coWx8hfBG6bpdnFsuL8JJHKwzlU2OdUJ78uLGgl190OYOEsIz5k3yK49nTyky4sOGmJsmds+fqR
rbURhDGu/tLAAK/6np3fai5ef4beZDbdhXrWS+rjOKSU0lRifUXU/JJFicG2PiX2B1InuqGLwGwAp/3
xoHqsuyNhTw== [email protected]

Set your git user name.

It is important that you set the user name and email address to use for any commits to the git repository:

$ git config --global user.name User Name
$ git config --global user.email [email protected]

Use the same email address that you used to sign up for your github account.

Forking the repository.

If you want to contribute to the project the best practice is to create a fork. To do so navigate to the project's repository and click on the fork button at the top right of the screen. If you are a member of multiple organisations you will be presented with a selection screen which can be used to select where to create the fork. Click on your user account to create the fork.

You can now clone your fork:

$ git clone [email protected]:<username>/<repository>.git

Keeping your fork in sync.

In order to easily pull down upstream changes to your fork you need to setup a new remote.

$ git remote add upstream [email protected]/<organisation>/<repository>.git

For the example of OpenWrt for the Creator Ci40 in the Creatordev organisation this would be

$ git remote add upstream [email protected]/CreatorDev/openwrt.git

You can now fetch from the upstream repository with:

$ git fetch upstream

And merge any new changes into your master branch with:

$ git checkout master
$ git merge upstream/master

Making changes.

The simplest way of working is to keep a clean master branch in the new fork and to create branches for each new pull request. This prevents merge conflicts with the upstream master branch, and allows you to make changes to your pull request if required.

To create a new branch:

$ git checkout master -b dev-branch1 --track

Note. The branch name here is important. It will show up in the git history so use something meaningful or suitably general

Once you have created your branch make your changes, then commit them to your new branch.

Commit messages.

For the commit message, the following rules apply:

  • The first line should be a brief summary of the patch.
  • Leave a blank line after the summary.
  • Provide a detailed description of the change.
  • Leave a blank line after the description.
  • If the patch relates to an issue, add a line with 'Ref: ISSUE_ID'.
  • Add a Git 'Signed-off-by' line using git commit -s or git commit --sign-off (see Signing your work below).

Example:


    Adds a new example feature xyz

    This patch adds example feature xyz. This feature merely acts
    as an example of how to commit something to the project.
    For real features this would contain some text
    describing in detail what the new feature actually does.

    Ref: <project>-<ID_number>
    Signed-off-by: User Name <[email protected]>

Signing your work.

CreatorDev projects require contributors to accept the Developer Certificate of Origin (DCO) from developercertificate.org. Github.com defines a contributor as "A contributor is someone from the outside not on the core development team of the project that wants to contribute some changes to a project."

The sign-off is a single line at the end of your commit comment to certify that you either wrote the supplied code or otherwise have the right to pass on the code as open source.

Certifying your contribution asserts that for the current submission the following statement is true:

Developer Certificate of Origin
Version 1.1

Copyright (C) 2004, 2006 The Linux Foundation and its contributors.
660 York Street, Suite 102,
San Francisco, CA 94110 USA

Everyone is permitted to copy and distribute verbatim copies of this
license document, but changing it is not allowed.

Developer's Certificate of Origin 1.1

By making a contribution to this project, I certify that:

(a) The contribution was created in whole or in part by me and I
    have the right to submit it under the open source license
    indicated in the file; or

(b) The contribution is based upon previous work that, to the best
    of my knowledge, is covered under an appropriate open source
    license and I have the right under that license to submit that
    work with modifications, whether created in whole or in part
    by me, under the same open source license (unless I am
    permitted to submit under a different license), as indicated
    in the file; or

(c) The contribution was provided directly to me by some other
    person who certified (a), (b) or (c) and I have not modified
    it.

(d) I understand and agree that this project and the contribution
    are public and that a record of the contribution (including all
    personal information I submit with it, including my sign-off) is
    maintained indefinitely and may be redistributed consistent with
    this project or the open source license(s) involved.

To certify your submission just add the following line to every git commit message to indicate that you accept the above DCO:

Signed-off-by: User Name <[email protected]>

If you set-up your user.name and user.email via git config, you can sign your commit automatically with git commit:

$ git commit --signoff

Pushing your changes to your branch.

If you specified --track when you created your new branch you should be able to simply push using

$ git push

If not you will either have to specify where to push your new commits.

$ git push origin dev_branch1:dev_branch1

or alternatively setup branch tracking

$ git push --set-upstream origin dev_branch1

Creating a pull request.

  • Navigate to https://github.com/*username*/*repository*/pulls
  • Click on New pull request
  • Select the repository's master as the base in the left hand box
  • Select the branch you wish to submit as a pull request in the right hand box.
  • Click the create button.

Note. Developers should only submit patches against the master branch.

An email will be sent to the project maintainers who will review your pull request.

If everything checks out no further action will be required.

You may wish to continue making other changes, in this case simply resync with the upstream and create a new branch. Do NOT add your new unrelated changes to the branch you used for the pull request as they will automatically be included in the request.

Making changes to a pull request.

You may be asked to make some changes before your pull request will be accepted. Any further commits that are pushed to the branch you used for the initial pull request will be automatically added to your pull request.

In some cases you may be asked to rebase your commits, either to bring them in-line with the current master branch, to tidy up any commit comments or to add a forgotten sign-off.