This guide documents the best way to make various types of contribution to Apache Eagle, including what is required before submitting a code change.

Contributing to Eagle doesn't just mean writing code. Helping new users on the mailing list, testing releases, and improving documentation are also welcome. In fact, proposing significant code changes usually requires first gaining experience and credibility within the community by helping in other ways. This is also a guide to becoming an effective contributor.


Before Making Contribution

Before contributing, you should know that Apache Eagle is using

Contributing by Helping Other Users

A great way to contribute to Eagle is to help answer user questions on the user@eagle.apache.org mailing list. There are always many new Eagle users; taking a few minutes to help answer a question is a very valuable community service.

Contributors should subscribe to this list and follow it in order to keep up to date on what's happening in Eagle. Answering questions is an excellent and visible way to help the community, which also demonstrates your expertise.

Contributing by Reviewing Changes

Changes to Eagle source code are proposed, reviewed and committed via Github (described later) at https://github.com/apache/eagle/pulls. Anyone can view and comment on active changes here. Reviewing others' changes is a good way to learn how the change process works and gain exposure to activity in various parts of the code. You can help by reviewing the changes and asking questions or pointing out issues -- as simple as typos or small issues of style.

Contributing Documentation Changes

Apache Eagle documentations are mainly host on:

You could make contribution 

Contributing Bug Reports

Contributing Code Changes

When you contribute code, you affirm that the contribution is your original work and that you license the work to the project under the project's open source license. Whether or not you state this explicitly, by submitting any copyrighted material via pull request, email, or other means you agree to license the material under the project's open source license and warrant that you have the legal authority to do so.

This section to help anyone who want to involve and contribute code to eagle project. Apache site have great documentation on how apache build the community and help the open source project. If one wants to know more detail on how apache works, he/she might want to check http://community.apache.org/.

JIRA

For who is new to eagle project, we have a label "new" to start with.

T Key Summary Assignee Reporter P Status Resolution Created Updated Due
Refresh

Pull Request

If you are ready to contribute code change. Here in this page we just focus on a consistent dev process to keep the project run smoothly.

  1. Find the existing Eagle JIRA that the change pertains to. If confirmed the change is new, create a new JIRA ticket if required with required fields
    • Issue Type
    • Priority
    • Affects Version
  2. Fork one's own feature branch from eagle official github (https://github.com/apache/eagle/)
  3. Fix bug / Develop feature in the feature branch. One might have multiple
  4. After development is done, send a github pull request. Like https://github.com/apache/eagle/pull/19. NOTE: Please make sure the pull request title is in format of EAGLE-${ticket_number} ${ticket_title}, so that ASF bot could help sync the pull request comments to JIRA automatically.

Review Process

The review process is for Apache Eagle committer only.

The committer should follow below process to review the contribution and merge the code.

  1. Review: Committers should review the pull request changes, leave comments and sigh off about whether accept the code change. (Reject/Recall/Pass)

  2. Merge: merge the patch of the pull request and push the merged code to apache/eagle (following process is temporary solution for manual merging, the automatic tool is under development  EAGLE-84)

    Pre-requisite

    Committer(reviewer) should have already cloned repo from apache github

    git clone https://git-wip-us.apache.org/repos/asf/eagle.git

    git-apply 

    > git pull https://git-wip-us.apache.org/repos/asf/eagle.git master # get latest
> wget https://patch-diff.githubusercontent.com/raw/apache/eagle/pull/19.patch && git apply 19.patch    # anyway you like to get the patch and apply
> # review the code; run the test; 
> git commit   # Commit with the commit MSG described below if everything looks good
> git push https://git-wip-us.apache.org/repos/asf/eagle.git master # push to upstream

    git-rebase when necessary

    > git pull https://git-wip-us.apache.org/repos/asf/eagle.git master # get latest
> git pull https://github.com/<contributor>/eagle.git EAGLE-ID
> git rebase -i # squash and modify the final committed message
> git commit 
> git push https://git-wip-us.apache.org/repos/asf/eagle.git master

    Or git-reset

    > git pull https://git-wip-us.apache.org/repos/asf/eagle.git master # get latest
> git pull https://github.com/<contributor>/eagle.git EAGLE-ID
> # review the code; run the test; 
> git reset origin/master
> git add .
> git commit -a  # Commit with the commit MSG described below if everything looks good
> git push https://git-wip-us.apache.org/repos/asf/eagle.git master # push to upstream

    Committers should follow an convention format to add appropriate commit message. The format should be:

    EAGLE-${jira_id} ${title}
${description}

${jira_url}

Author: @${committer_github_id} <author_email>
Reviewer: @${reviewer_github_id} <reviewer_email>

Closes #${pull_request_id}

     

  3. Close: Committer to close the JIRA ticket. (Pull request will be close automatically)

 

Here is a diagram to show the workflow above:

  • No labels