Skip to content

Commit e72d3d0

Browse files
barnascbarnasc
committed
add contributing and development documents
1 parent e8f9ef4 commit e72d3d0

File tree

2 files changed

+263
-0
lines changed

2 files changed

+263
-0
lines changed

‎CONTRIBUTING.md

Lines changed: 113 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,113 @@
1+
How to Contribute
2+
=================
3+
4+
This repository is owned by the [Accellera Systems Initiative][1] and
5+
is maintained by the SystemC Common Practices Working Group
6+
according to the [Accellera Policies and Procedures][2].
7+
8+
**Contributions to this reference implementation can only be
9+
accepted from Accellera members.**
10+
11+
### Join the Accellera SystemC Common Practices Working Group
12+
13+
If you would like to contribute to the development of one of the SystemC
14+
reference implementations, have your company, organization, or university
15+
join Accellera and its working groups.
16+
Find out more information at http://www.accellera.org/about/join.
17+
If your company, organization or university is already an Accellera member,
18+
you can request to [join the SystemC Language Working Group here][3].
19+
20+
### Join the SystemC community
21+
22+
If you are not an Accellera member, please join the **[SystemC Forum][4]**
23+
to provide feedback, report bugs and join the general
24+
discussion around the evolution of SystemC and its ecosystem.
25+
26+
---------------------------------------------------------------------
27+
Issue reporting
28+
---------------------------------------------------------------------
29+
30+
You can post issues, bugs and suggestions of general interest to the
31+
[SystemC Forum][4] or [Issue tracker][5]. When reporting bugs, please specify
32+
the following information (if applicable):
33+
34+
1. SystemC library version
35+
2. platform, compiler, flags
36+
3. description of the problem
37+
4. steps to reproduce the problem
38+
5. compile/runtime warnings and errors
39+
6. code sample, not more than 100 lines to demonstrate the problem
40+
41+
> **Note**
42+
> All bugs will only be tested against the latest publicly available
43+
> version of the product.
44+
45+
> **Note**
46+
> All C++ compilers that SystemC supports have bugs of different
47+
> degree of severity. We cannot fix those bugs.
48+
> Please report them to the compiler vendor.
49+
50+
---------------------------------------------------------------------
51+
Patch submission
52+
---------------------------------------------------------------------
53+
54+
The following **sign-off procedure** is established to ensure that
55+
patches submitted for inclusion into this Accellera reference
56+
implementation are properly licensed under the
57+
[Apache License Version 2.0](LICENSE).
58+
59+
The sign-off is a simple line at the end of the explanation for the
60+
patch (or commit message), which certifies that you wrote it yourself
61+
or otherwise have the right to pass it on as an open-source patch:
62+
63+
### Accellera Developer's Certificate of Origin
64+
65+
By making a signed-off contribution to this Accellera project,
66+
I certify that:
67+
68+
1. The contribution was created in whole or in part by me and I have
69+
the right to submit it under the Apache License Version 2.0
70+
(see LICENSE).
71+
72+
2. The contribution was provided directly to me by some other person
73+
who certified (1) above, and I am forwarding it without
74+
modification.
75+
76+
3. I understand and agree that this Accellera project and the
77+
contribution are public and that a record of the contribution
78+
(including all personal information I submit with it, including
79+
my sign-off) is maintained indefinitely and may be redistributed
80+
in accordance with this project or the Apache License Version 2.0.
81+
82+
If you can certify the above *Accellera Developer's Certificate of Origin*,
83+
please use `git commit --signoff` to add a line of the form:
84+
```
85+
Signed-off-by: Ima Contributor <[email protected]>
86+
```
87+
using your real name (no pseudonyms or anonymous contributions).
88+
89+
> **Note**
90+
> For Accellera members, contributions are already bound by the
91+
> [Accellera policies and procedures][2] and the sign-off is optional,
92+
> but recommended. For **non-Accellera** members, the sign-off is
93+
> **mandatory** for consideration by the Accellera WGs.
94+
95+
When submitting a pull-request against the public repository, the
96+
contribution may be considered by the Accellera WGs for inclusion. It
97+
stays under the sole governance
98+
of the corresponding WGs to decide whether a contribution will be included
99+
in the reference implementation (or future Accellera standards).
100+
101+
---------------------------------------------------------------------
102+
Repository organization
103+
---------------------------------------------------------------------
104+
105+
More information on the repository organization can be found in the
106+
[Development process description](./docs/DEVELOPMENT.md).
107+
108+
109+
[1]: https://www.accellera.org
110+
[2]: https://accellera.org/about/policies-and-procedures
111+
[3]: https://workspace.accellera.org/apps/org/workgroup/lwg/
112+
[4]: https://forums.accellera.org/forum/9-systemc/
113+
[5]: https://github.com/accellera-official/systemc-common-practices/issues

‎docs/DEVELOPMENT.md

Lines changed: 150 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,150 @@
1+
Development process of the Accellera SystemC Common Practices library
2+
=====================================================================
3+
4+
This document focuses on the technical aspects related to the development
5+
of the SystemC Common Practices library.
6+
Legal and formal procedures are documented at
7+
8+
https://accellera.org/about/policies-and-procedures.
9+
10+
---------------------------------------------------------------------
11+
Repository setup
12+
---------------------------------------------------------------------
13+
14+
The central source code repository of the Accellera Common Practices library
15+
is hosted at [GitHub](https://github.com/accellera-official/).
16+
The read-only repository can be found at
17+
18+
* https://github.com/accellera-official/systemc-common-practices
19+
20+
### Creating a personal fork
21+
22+
In order to contribute changes to the repository, it is recommended to create
23+
personal (or company-based) [forks][2] of the repository on GitHub and push
24+
the proposed changes (bugfixes, features, ...) there. Details of the intended
25+
work-flow are described in the next [section](#basic-branch-setup). It is
26+
convenient to add this GitHub fork as a remote to your local clone of the
27+
repository:
28+
29+
cd <repo>/
30+
git remote add origin [email protected]:<your-account>/<repo>.git
31+
git branch --set-upstream master origin/master
32+
33+
Contributions to the Accellera SystemC Common Practices library should comply with the
34+
[contributing guidelines][1].
35+
36+
Any changes can then be pushed to GitHub using:
37+
38+
git push [options] [<repository>] [<refspec>...]
39+
40+
* If you omit the `<repository>`, the default destination is
41+
the remote of the current branch (or `origin`).
42+
* The `<refspec>` basically follows the format
43+
`<local-branch>:<remote-branch>`, or just `<branch>`, if
44+
both are the same.
45+
* Omitting the `<refspec>` pushes all branches with 'matching'
46+
remote branches to the repository.
47+
48+
A basic cheat sheet containing the an overview of the general
49+
Git commands and workflow can be found [online][3].
50+
51+
---------------------------------------------------------------------
52+
Development flow
53+
---------------------------------------------------------------------
54+
55+
### Adding a feature (set) or bug fix
56+
57+
The development of a new contribution in form of a feature or a
58+
complex bug fix is best done in a new feature branch, which is
59+
forked and checked out from the `main` branch:
60+
61+
git checkout -b <company>-<feature-xyz> main
62+
63+
Then code up the new contribution. Please try to facilitate code
64+
review by other Accellera members by logically grouping your changes into
65+
one commit per addressed issue. For the commit messages, please
66+
consider to follow these suggestions:
67+
68+
> *Note:* **Commit messages**
69+
>
70+
> Though not required, it's a good idea to begin the commit message with
71+
> a single short (less than 50 character) line summarizing the change,
72+
> followed by a blank line and then a more thorough description. Tools
73+
> that turn commits into email, for example, use the first line on the
74+
> `Subject:` line and the rest of the commit in the body.
75+
76+
> *Note:* **Sign-off procedure for commits**
77+
>
78+
> In order to document that contributions are submitted under the
79+
> Apache-2.0 license (see `LICENSE`), a sign-off procedure is
80+
> defined in the [contributing guidelines][1].
81+
82+
During the development of the contribution, the `main` branch may
83+
receive other commits. In that case, consider rebasing the commits in
84+
your feature branch onto the `HEAD` of the `main` branch to keep the
85+
history clean. Once the contribution is ready for review by the
86+
working group, push the feature branch in your fork of the respective
87+
repository on GitHub:
88+
89+
git push <your-github-fork-remote-name> <company>-<feature-xyz>
90+
91+
Then, send a [pull request][4] either manually or via [GitHub][4] to
92+
initiate the code review by the Accellera working group members.
93+
The summary can be manually generated by
94+
95+
git request-pull main [email protected]/<account>/<repo>.git \
96+
<company-feature-xyz>
97+
98+
To review the proposed contributions, one can either browse the
99+
repository at GitHub, or add the remote location to a local
100+
clone of the repository
101+
102+
# add the fork to your set of "remotes"
103+
git remote add <remote-name> [email protected]/<account>/<repo>.git
104+
git fetch <remote-name>
105+
106+
# examine differences
107+
git diff main..<remote-name>/<company-feature-xyz>
108+
git log <remote-name>/<company-feature-xyz>
109+
110+
After the contribution is accepted, it will be merged into the
111+
`main` branch by the responsible source code maintainer. This should
112+
be done with an explicit *merge commit*, to keep the individual
113+
contributions separated:
114+
115+
git merge --no-ff --log \
116+
<remote-name>/<company-feature-xyz>
117+
118+
Instead of fully merging the contribution, the maintainer may choose
119+
to cherry-pick individual commits or to rebase the feature branch on
120+
an intermittently updated `main`. He may also request additional
121+
changes to be done by the submitter. In that case, the submitter may
122+
need to merge recent changes to the `main` branch into his feature
123+
branch before carrying out the requested changes.
124+
125+
After the contribution has been fully merged into the `main` branch, the
126+
feature branch in the local and Github fork may be deleted.
127+
128+
git branch -d <company-feature-xyz> # delete local branch
129+
git push origin :<company-feature-xyz> # delete remote branch
130+
131+
---------------------------------------------------------------------
132+
Issue tracking
133+
---------------------------------------------------------------------
134+
135+
Open issues (bugs, cleanups, features) related to the reference
136+
implementation of SystemC Common Practices library are tracked via GitHub:
137+
138+
* <https://github.com/accellera-official/systemc-common-practices/issues>
139+
140+
The discussion on issues usually starts on the Accellera Working Group
141+
email reflector or during the working group meetings. After an initial
142+
consensus on the "validity" of the issue, the issue is added to the
143+
issue tracking system, a classification is done (including a target
144+
milestone), and preferably a responsible person is assigned.
145+
146+
147+
[1]: ../CONTRIBUTING.md "How to Contribute"
148+
[2]: https://docs.github.com/en/get-started/quickstart/fork-a-repo
149+
[3]: http://zrusin.blogspot.de/2007/09/git-cheat-sheet.html "Git Cheat Sheet"
150+
[4]: https://help.github.com/articles/using-pull-requests "Using Pull Requests - github:help"

0 commit comments

Comments
 (0)